home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-03 / fgl110b.zip / USER1.TXT < prev    next >
Text File  |  1992-02-07  |  316KB  |  6,998 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11. Fastgraph (tm)
  12.  
  13.  
  14.  
  15.  
  16.  
  17. User's Guide
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.                                                            Ted Gruber Software
  54.                                                                   PO Box 13408
  55.                                                           Las Vegas, NV  89112
  56.  
  57.                                                                 (702) 735-1980
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66. Copyright (c) 1991,1992 by Ted Gruber Software.
  67.  
  68. All rights reserved.  No part of this publication may be reproduced, stored
  69. in a retrieval system, or transmitted by any means, electronic, mechanical,
  70. photocopying, recording, or otherwise, without express written permission
  71. from Ted Gruber Software.  The software described in this publication is
  72. furnished under a license agreement and may be used or copied only in
  73. accordance with the terms of that agreement.
  74.  
  75. This publication and its associated software are sold without warranties,
  76. either expressed or implied, regarding their merchantability or fitness for
  77. any particular application or purpose.  The information in this publication
  78. is subject to change without notice and does not represent a commitment on
  79. the part of Ted Gruber Software.  In no event shall Ted Gruber Software be
  80. liable for any loss of profit or any other commercial damage, including but
  81. not limited to special, incidental, consequential, or other damages resulting
  82. from the use of or the inability to use this product, even if Ted Gruber
  83. Software has been notified of the possibility of such damages.
  84.  
  85.  
  86. Second Printing, January 1992
  87.  
  88. Fastgraph version 2.10
  89. Fastgraph/Light version 1.10
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98. DFI is a registered trademark of Diamond Flower Electric Instrument Co., Inc.
  99. Fastgraph and Fastgraph/Light  are trademarks of Ted Gruber Software.
  100. Hercules is a trademark of Hercules Computer Technology.
  101. IBM, IBM PC, IBM PC/XT, IBM PC/AT, PS/2, PCjr, and PC-DOS are registered
  102.    trademarks of International Business Machines, Inc.
  103. Intel is a registered trademark of Intel Corporation.
  104. Logitech is a trademark of LOGITECH, Inc.
  105. Microsoft, Microsoft Mouse, and MS-DOS are registered trademarks of Microsoft
  106.    Corporation.
  107. PC Paintbrush is a registered trademark of ZSoft, Inc.
  108. QuickBASIC and QuickC are trademarks of Microsoft Corporation.
  109. Tandy is a registered trademark of Tandy Corporation.
  110. Turbo C and Turbo Pascal are registered trademarks of Borland International,
  111.    Inc.
  112.  
  113.  
  114. All other brand and product names mentioned in this publication are
  115. trademarks or registered trademarks of their respective holders.
  116.  
  117.                       T a b l e   o f   C o n t e n t s
  118.  
  119. Chapter 1  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .    1
  120.      What is Fastgraph? . . . . . . . . . . . . . . . . . . . . . . . . .    2
  121.      Fastgraph/Light  . . . . . . . . . . . . . . . . . . . . . . . . . .    2
  122.      Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . .    2
  123.      Supported Compilers  . . . . . . . . . . . . . . . . . . . . . . . .    3
  124.      Memory Models  . . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  125.      Installing Fastgraph . . . . . . . . . . . . . . . . . . . . . . . .    4
  126.      Fastgraph Naming Conventions . . . . . . . . . . . . . . . . . . . .    4
  127.      Compilation and Linking  . . . . . . . . . . . . . . . . . . . . . .    5
  128.           Borland C++ . . . . . . . . . . . . . . . . . . . . . . . . . .    7
  129.           Microsoft C . . . . . . . . . . . . . . . . . . . . . . . . . .    8
  130.           Microsoft FORTRAN . . . . . . . . . . . . . . . . . . . . . . .    9
  131.           Microsoft QuickBASIC  . . . . . . . . . . . . . . . . . . . . .   10
  132.           Microsoft QuickC  . . . . . . . . . . . . . . . . . . . . . . .   11
  133.           Power C . . . . . . . . . . . . . . . . . . . . . . . . . . . .   13
  134.           Turbo C and Turbo C++ . . . . . . . . . . . . . . . . . . . . .   14
  135.           Turbo Pascal  . . . . . . . . . . . . . . . . . . . . . . . . .   15
  136.      Fastgraph/Light Video Driver . . . . . . . . . . . . . . . . . . . .   16
  137.  
  138. Chapter 2  PC and PS/2 Video Modes  . . . . . . . . . . . . . . . . . . .   17
  139.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   18
  140.      Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   19
  141.      Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . .   21
  142.           CGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   21
  143.           Tandy 1000 and PCjr Graphics Modes  . . . . . . . . . . . . . .   22
  144.           Hercules Graphics Modes . . . . . . . . . . . . . . . . . . . .   22
  145.           EGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   23
  146.           VGA and MCGA Graphics Modes . . . . . . . . . . . . . . . . . .   24
  147.  
  148. Chapter 3  Initializing the Video Environment . . . . . . . . . . . . . .   27
  149.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   28
  150.      Establishing a Text Mode . . . . . . . . . . . . . . . . . . . . . .   28
  151.      43-line and 50-line Text Modes . . . . . . . . . . . . . . . . . . .   31
  152.      Establishing a Graphics Mode . . . . . . . . . . . . . . . . . . . .   32
  153.      Summary of Video Initialization Routines . . . . . . . . . . . . . .   36
  154.  
  155. Chapter 4  Coordinate Systems . . . . . . . . . . . . . . . . . . . . . .   39
  156.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   40
  157.      Character Space  . . . . . . . . . . . . . . . . . . . . . . . . . .   40
  158.      Screen Space . . . . . . . . . . . . . . . . . . . . . . . . . . . .   41
  159.      World Space  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   42
  160.      Conversion Routines  . . . . . . . . . . . . . . . . . . . . . . . .   44
  161.      Summary of Coordinate Routines . . . . . . . . . . . . . . . . . . .   44
  162.  
  163. Chapter 5  The Use of Color . . . . . . . . . . . . . . . . . . . . . . .   47
  164.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   48
  165.      Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   48
  166.           Color Modes . . . . . . . . . . . . . . . . . . . . . . . . . .   48
  167.           Monochrome Mode . . . . . . . . . . . . . . . . . . . . . . . .   49
  168.      Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . .   50
  169.           CGA Color Modes . . . . . . . . . . . . . . . . . . . . . . . .   51
  170.           CGA Two-Color Mode  . . . . . . . . . . . . . . . . . . . . . .   52
  171.           Tandy and PCjr Modes  . . . . . . . . . . . . . . . . . . . . .   53
  172.           Hercules Mode . . . . . . . . . . . . . . . . . . . . . . . . .   54
  173.  
  174.                                      iii
  175.  
  176.           Hercules Low-Resolution Mode  . . . . . . . . . . . . . . . . .   55
  177.           EGA 200-Line Modes  . . . . . . . . . . . . . . . . . . . . . .   56
  178.           EGA Monochrome Mode . . . . . . . . . . . . . . . . . . . . . .   58
  179.           EGA Enhanced Mode . . . . . . . . . . . . . . . . . . . . . . .   59
  180.           VGA and MCGA Two-Color Mode . . . . . . . . . . . . . . . . . .   61
  181.           VGA 16-Color Mode . . . . . . . . . . . . . . . . . . . . . . .   63
  182.           VGA and MCGA 256-Color Modes  . . . . . . . . . . . . . . . . .   64
  183.      RGB Color Mapping  . . . . . . . . . . . . . . . . . . . . . . . . .   68
  184.      Defining All Palette Registers . . . . . . . . . . . . . . . . . . .   69
  185.      Virtual Colors . . . . . . . . . . . . . . . . . . . . . . . . . . .   69
  186.      A Multiple-Mode Example  . . . . . . . . . . . . . . . . . . . . . .   71
  187.      Summary of Color-Related Routines  . . . . . . . . . . . . . . . . .   73
  188.  
  189. Chapter 6  Graphics Fundamentals  . . . . . . . . . . . . . . . . . . . .   75
  190.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   76
  191.      Clearing the Screen  . . . . . . . . . . . . . . . . . . . . . . . .   76
  192.      Clipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   76
  193.      Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   76
  194.      The Graphics Cursor  . . . . . . . . . . . . . . . . . . . . . . . .   79
  195.      Solid Lines  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   79
  196.      Dashed Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . .   82
  197.      Polygons, Circles, and Ellipses  . . . . . . . . . . . . . . . . . .   83
  198.      Solid Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . .   86
  199.      Unfilled Rectangles  . . . . . . . . . . . . . . . . . . . . . . . .   87
  200.      Dithered Rectangles  . . . . . . . . . . . . . . . . . . . . . . . .   88
  201.      Region Fill  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   95
  202.      Summary of Fundamental Graphics Routines . . . . . . . . . . . . . .   96
  203.  
  204. Chapter 7  Character Display Routines . . . . . . . . . . . . . . . . . .   99
  205.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  100
  206.      Character Space  . . . . . . . . . . . . . . . . . . . . . . . . . .  100
  207.      Hardware Characters  . . . . . . . . . . . . . . . . . . . . . . . .  101
  208.      Conversion Routines  . . . . . . . . . . . . . . . . . . . . . . . .  107
  209.      Software Characters  . . . . . . . . . . . . . . . . . . . . . . . .  108
  210.      Bit-Mapped Characters  . . . . . . . . . . . . . . . . . . . . . . .  114
  211.      Summary of Character Display Routines  . . . . . . . . . . . . . . .  114
  212.  
  213. Chapter 8  Video Page Management  . . . . . . . . . . . . . . . . . . . .  117
  214.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  118
  215.      Physical Pages and Virtual Pages . . . . . . . . . . . . . . . . . .  118
  216.      Pages With Special Meanings  . . . . . . . . . . . . . . . . . . . .  119
  217.      Some Simple Examples . . . . . . . . . . . . . . . . . . . . . . . .  119
  218.      Text Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . .  126
  219.      Obtaining Video Page Information . . . . . . . . . . . . . . . . . .  127
  220.      Considerations for Virtual Pages . . . . . . . . . . . . . . . . . .  128
  221.      Logical Pages  . . . . . . . . . . . . . . . . . . . . . . . . . . .  129
  222.      Video Page Resizing  . . . . . . . . . . . . . . . . . . . . . . . .  131
  223.      Summary of Video Page Management Routines  . . . . . . . . . . . . .  132
  224.  
  225. Chapter 9 Images and Image Management . . . . . . . . . . . . . . . . . .  135
  226.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  136
  227.      Mode-Independent Bit-Mapped Images . . . . . . . . . . . . . . . . .  136
  228.      Mode-Specific Bit-Mapped Images  . . . . . . . . . . . . . . . . . .  140
  229.           Regular Images  . . . . . . . . . . . . . . . . . . . . . . . .  141
  230.           Clipped Images  . . . . . . . . . . . . . . . . . . . . . . . .  148
  231.           Reversed Images . . . . . . . . . . . . . . . . . . . . . . . .  149
  232.  
  233.                                       iv
  234.  
  235.           Reversed Clipped Images . . . . . . . . . . . . . . . . . . . .  149
  236.           Some Examples . . . . . . . . . . . . . . . . . . . . . . . . .  149
  237.      Pixel Run Maps . . . . . . . . . . . . . . . . . . . . . . . . . . .  152
  238.      Display Patterns . . . . . . . . . . . . . . . . . . . . . . . . . .  158
  239.      PCX Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  164
  240.      Masking Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . .  166
  241.      Retrieving Images  . . . . . . . . . . . . . . . . . . . . . . . . .  169
  242.      Byte Boundaries  . . . . . . . . . . . . . . . . . . . . . . . . . .  174
  243.      Image Transfer Routines  . . . . . . . . . . . . . . . . . . . . . .  175
  244.      Summary of Image Display Routines  . . . . . . . . . . . . . . . . .  184
  245.  
  246. Chapter 10  Animation Techniques  . . . . . . . . . . . . . . . . . . . .  187
  247.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  188
  248.      Simple Animation . . . . . . . . . . . . . . . . . . . . . . . . . .  188
  249.      XOR Animation  . . . . . . . . . . . . . . . . . . . . . . . . . . .  190
  250.      Static Frame Animation . . . . . . . . . . . . . . . . . . . . . . .  192
  251.      Dynamic Frame Animation  . . . . . . . . . . . . . . . . . . . . . .  194
  252.      Page Flipping  . . . . . . . . . . . . . . . . . . . . . . . . . . .  196
  253.      Summary of Animation Techniques  . . . . . . . . . . . . . . . . . .  198
  254.  
  255. Chapter 11  Special Effects . . . . . . . . . . . . . . . . . . . . . . .  199
  256.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  200
  257.      Screen Dissolving  . . . . . . . . . . . . . . . . . . . . . . . . .  200
  258.      Scrolling  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  202
  259.      Changing the Screen Origin . . . . . . . . . . . . . . . . . . . . .  205
  260.      Summary of Special Effects Routines  . . . . . . . . . . . . . . . .  208
  261.  
  262. Chapter 12  Input Device Support  . . . . . . . . . . . . . . . . . . . .  209
  263.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  210
  264.      Keyboard Support . . . . . . . . . . . . . . . . . . . . . . . . . .  210
  265.           Reading Keystrokes  . . . . . . . . . . . . . . . . . . . . . .  212
  266.           Testing and Setting Key States  . . . . . . . . . . . . . . . .  213
  267.      Mouse Support  . . . . . . . . . . . . . . . . . . . . . . . . . . .  214
  268.           Initializing the Mouse  . . . . . . . . . . . . . . . . . . . .  215
  269.           Controlling the Mouse Cursor  . . . . . . . . . . . . . . . . .  216
  270.           Reporting the Mouse Status  . . . . . . . . . . . . . . . . . .  218
  271.           Defining the Mouse Cursor . . . . . . . . . . . . . . . . . . .  220
  272.      Joystick Support . . . . . . . . . . . . . . . . . . . . . . . . . .  227
  273.           Initializing Joysticks  . . . . . . . . . . . . . . . . . . . .  227
  274.           Reporting Joystick Status . . . . . . . . . . . . . . . . . . .  227
  275.           Keyboard Emulation  . . . . . . . . . . . . . . . . . . . . . .  229
  276.           Special Joystick Considerations . . . . . . . . . . . . . . . .  230
  277.      Summary of Input Routines  . . . . . . . . . . . . . . . . . . . . .  231
  278.  
  279. Chapter 13  Sound Effects . . . . . . . . . . . . . . . . . . . . . . . .  233
  280.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  234
  281.      Sound Sources  . . . . . . . . . . . . . . . . . . . . . . . . . . .  234
  282.      Synchronous Sound  . . . . . . . . . . . . . . . . . . . . . . . . .  234
  283.      Asynchronous Sound . . . . . . . . . . . . . . . . . . . . . . . . .  239
  284.      Summary of Sound Routines  . . . . . . . . . . . . . . . . . . . . .  244
  285.  
  286. Chapter 14  Program Timing  . . . . . . . . . . . . . . . . . . . . . . .  247
  287.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  248
  288.      Real-Time Routines . . . . . . . . . . . . . . . . . . . . . . . . .  248
  289.      Routines Dependent on the System Speed . . . . . . . . . . . . . . .  249
  290.      Summary of Timing Routines . . . . . . . . . . . . . . . . . . . . .  251
  291.  
  292.                                       v
  293.  
  294. Chapter 15  Miscellaneous Routines  . . . . . . . . . . . . . . . . . . .  253
  295.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  254
  296.      Determining Available Memory . . . . . . . . . . . . . . . . . . . .  254
  297.      Choosing the Video Memory Update Function  . . . . . . . . . . . . .  255
  298.      Summary of Miscellaneous Routines  . . . . . . . . . . . . . . . . .  256
  299.  
  300. Appendix A  Fastgraph Utilities . . . . . . . . . . . . . . . . . . . . .  257
  301.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  258
  302.      SNAPSHOT Utility . . . . . . . . . . . . . . . . . . . . . . . . . .  258
  303.      CLIP Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . .  259
  304.      CONVERT Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  261
  305.      EDITSPR Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  261
  306.      GrabRGB Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  262
  307.      HERCFIX Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  263
  308.  
  309. Appendix B  Using Fastgraph from Assembly Language  . . . . . . . . . . .  265
  310.  
  311. Appendix C  Interrupts and Fastgraph  . . . . . . . . . . . . . . . . . .  269
  312.      Interrupts Used by Fastgraph . . . . . . . . . . . . . . . . . . . .  270
  313.      Extending the Time-of-Day Interrupt  . . . . . . . . . . . . . . . .  270
  314.  
  315. Appendix D  Contents of the Compiler-Specific Libraries . . . . . . . . .  277
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.                                       vi
  352.  
  353.  
  354. Chapter 1
  355.  
  356. Introduction
  357. 2  Fastgraph User's Guide
  358.  
  359.  
  360. What is Fastgraph?
  361.  
  362.      Fastgraph is a library of more than 170 highly-optimized routines that
  363. are callable from high-level and assembly language programs running under the
  364. MS-DOS or PC-DOS operating systems.  This collection of routines provides a
  365. programmer with proven, powerful tools to take command of the PC and PS/2
  366. video environment.  In addition to its video support, Fastgraph also contains
  367. routines to perform keyboard, mouse, and joystick control, as well as music
  368. and sound capabilities.  Fastgraph is an ideal development tool for
  369. entertainment and educational software, presentation graphics products,
  370. scientific and engineering applications, CAD/CAM, animation, or any
  371. application that demands robust graphics.
  372.  
  373.      As its name implies, the most notable feature of Fastgraph is its speed.
  374. Virtually all of Fastgraph is written in 8086 assembly language, and each
  375. routine has been optimized by hand to provide maximum performance.
  376.  
  377.      Fastgraph supports all the standard text and graphics video modes used
  378. by the IBM PC (PC, PC/XT, and PC/AT) and PS/2 families and compatible
  379. systems.  In addition, Fastgraph provides support for four extended VGA
  380. graphics modes and a 16-color graphics mode unique to Tandy 1000 series
  381. computers and the PCjr.  Even though the graphics mode of the Hercules
  382. Graphics Card is not an IBM standard, its popularity has made it a de facto
  383. standard, and for this reason Fastgraph also supports it.  A complete
  384. discussion of all of Fastgraph's supported video modes appears in the next
  385. chapter.
  386.  
  387.  
  388. Fastgraph/Light
  389.  
  390.      Fastgraph/Light is a subset of Fastgraph.  It includes all of
  391. Fastgraph's features except the redefinable world space coordinate system and
  392. the routines pertaining to software characters.  Programs created using
  393. Fastgraph/Light are 100% source code compatible with Fastgraph.
  394.  
  395.      The most important difference between Fastgraph/Light and Fastgraph is
  396. the method of running a program created with the two products.  With
  397. Fastgraph, any of its routines used in your program are linked directly into
  398. the resulting .EXE file.  With Fastgraph/Light, however, this is not the
  399. case.  Instead, the Fastgraph/Light routines provide an interface to an
  400. external driver, called the Fastgraph/Light Video Driver, which must be
  401. loaded separately before running programs that call any Fastgraph/Light
  402. routines.  A further discussion of this driver begins on page 16.
  403.  
  404.      In this document, and in the accompanying Fastgraph Reference Manual,
  405. references to Fastgraph also apply to Fastgraph/Light unless stated
  406. otherwise.
  407.  
  408.  
  409. Prerequisite Knowledge
  410.  
  411.      Fastgraph is a programming tool, which means programmers are its
  412. intended audience.  For this reason, the Fastgraph User's Guide and the
  413. accompanying Fastgraph Reference Manual assume you have a knowledge of
  414. programming.  Additionally, a knowledge of converting numbers between binary,
  415. decimal, and hexadecimal is assumed.
  416.                                                    Chapter 1:  Introduction  3
  417.  
  418.      Virtually all the examples in this manual are written in the C
  419. programming language, so a knowledge of C would be especially helpful.  The
  420. examples intentionally avoid using any of C's features and idioms that might
  421. not be readily apparent to a programmer unfamiliar with C.  Finally, we'd
  422. like to point out that the examples are intended to be read not by
  423. themselves, but as part of the surrounding text.
  424.  
  425.  
  426. Supported Compilers
  427.  
  428.      You can use Fastgraph with any compilers or assemblers that use the same
  429. calling and naming conventions as the small, medium, or large memory models
  430. of the supported compilers.  Mixed language programming is allowed where
  431. supported by the language translators and linker being used.  Fastgraph
  432. supports the following compilers:
  433.  
  434.        Borland C++ (version 2.0 or later)
  435.        Microsoft C (version 5.0 or later)
  436.        Microsoft FORTRAN (version 4.0 or later)
  437.        Microsoft QuickBASIC (version 4.0 or later)
  438.        Microsoft QuickC (version 2.0 or later)
  439.        Power C (version 2.0 or later)
  440.        Turbo C or Turbo C++ (version 2.0 or later)
  441.        Turbo Pascal (version 6.0 or later)
  442.  
  443. The listed version numbers are the compiler versions under which Fastgraph
  444. was developed and tested.  Fastgraph may or may not work with earlier
  445. versions of these compilers.  The use of Fastgraph from assembly language
  446. programs is addressed in Appendix B.
  447.  
  448.  
  449. Memory Models
  450.  
  451.      All of Fastgraph's supported compilers except QuickBASIC and Turbo
  452. Pascal offer several memory models.  A memory model defines how memory is set
  453. up for a program's code and data segments.  Fastgraph includes libraries for
  454. the small, medium, and large memory models.
  455.  
  456.      The small memory model allows for one code segment and one data segment.
  457. Programs that use the small model can thus have a maximum of 64K bytes of
  458. code and 64K bytes of data.  Because the small model implements call
  459. instructions and data references through near pointers, it produces the most
  460. efficient code of the three supported memory models.
  461.  
  462.      The medium memory model allows for multiple code segments and one data
  463. segment.  Programs that use the medium model thus have no compiler-imposed
  464. limit to the code size (although no one segment can exceed 64K bytes) and a
  465. maximum of 64K bytes of data.  Like the small model, the medium model
  466. implements data references through near pointers, but it implements call
  467. instructions through far pointers.  The use of far pointers adds two bytes of
  468. code and 13 clock cycles for each subprogram call.  The medium model is a
  469. popular choice among programmers.
  470.  
  471.      The large memory model supports multiple code and data segments.
  472. Programs that use the large model do not have any compiler-imposed limits for
  473. code and data sizes.  However, no single code or data segment can exceed 64K
  474. bytes.  Because the large model implements call instructions and data
  475. 4  Fastgraph User's Guide
  476.  
  477. references through far pointers, it produces the least efficient code of the
  478. three supported memory models.
  479.  
  480.      For more information about memory models, please refer to the user's
  481. guide or reference manual for the compilers you'll be using with Fastgraph.
  482.  
  483.  
  484. Installing Fastgraph
  485.  
  486.      This section explains how to use the INSTALL program to load Fastgraph
  487. (or Fastgraph/Light) and its related files on a hard disk.  The installation
  488. program lets you select the compilers and memory models you wish to use with
  489. Fastgraph.  It also gives you the opportunity to load many example Fastgraph
  490. programs specific to the compilers you choose.
  491.  
  492.      Before you start the installation, you should use the DOS commands COPY
  493. or DISKCOPY to make working copies of the Fastgraph distribution disks (refer
  494. to your DOS reference manual if you are unfamiliar with these commands).
  495. Once you have created the working copies, store the original disks in a safe
  496. place.  Install Fastgraph from the working copies you just created.
  497.  
  498.      For simplicity, we'll assume you are installing Fastgraph from the
  499. diskette drive A: to the hard drive C:, but you can of course use any
  500. available drives.  The Fastgraph distribution disk labeled Installation and
  501. Utilities contains Fastgraph's INSTALL program.  Place this disk in the A:
  502. drive, make A: your current drive, and enter the command INSTALL, as shown
  503. below.
  504.  
  505.                                   C> A:
  506.                                   A> INSTALL
  507.  
  508. From this point, just follow the directions on each screen.  At any time, you
  509. can press the Esc key to abort the installation.
  510.  
  511.      The INSTALL program will ask you for the compilers and memory models
  512. you'll use with Fastgraph, as well as the directory names for the Fastgraph
  513. utilities, libraries, and include files.  For the utilities, the default
  514. directory is C:\FG.  For the include files and libraries, we recommend using
  515. directories where the compiler you've chosen normally searches for such
  516. files.  INSTALL will automatically try to determine these directories and
  517. propose them as defaults.
  518.  
  519.      You can install support for additional compilers or memory models at any
  520. time.  If you choose to do this, you should use the command INSTALL /L to
  521. avoid copying the files common to all compilers and memory models.
  522.  
  523.  
  524. Fastgraph Naming Conventions
  525.  
  526.      The names of all Fastgraph routines begin with the three characters
  527. "fg_".  This prefix helps identify Fastgraph routines within a program, and
  528. it also reduces the chance of name conflicts that might otherwise occur
  529. between Fastgraph and other third party libraries.
  530.  
  531.      Because QuickBASIC does not permit underscores in identifiers, the
  532. QuickBASIC versions of Fastgraph routines begin with the two characters "FG".
  533.                                                    Chapter 1:  Introduction  5
  534.  
  535. For example, the fg_version routine is named FGversion in the QuickBASIC
  536. libraries.  All subsequent references to Fastgraph routines in this manual
  537. and the accompanying Fastgraph Reference Manual will use the fg_ naming
  538. convention instead of the QuickBASIC names.
  539.  
  540.  
  541. Compilation and Linking
  542.  
  543.      To build an executable (.EXE) file for a program that uses Fastgraph
  544. routines, first compile or assemble the program using the small, medium, or
  545. large memory model.  This step produces an object file, which is then linked
  546. with Fastgraph and any other object libraries to produce an executable file.
  547.  
  548.      Examples 1-1 through 1-4 use the Fastgraph routine fg_version to display
  549. the version number for your copy of Fastgraph.  These examples are
  550. respectively written in the four high-level languages Fastgraph supports:
  551. C/C++, BASIC, FORTRAN, and Pascal.  If you loaded the example programs when
  552. you installed Fastgraph, the files \FG\EXAMPLES\01-01.C, 01-02.BAS,
  553. 01-03.FOR, and 01-04.PAS contain the source code for these examples.  You can
  554. use them to test the compilation and linking process for the memory models
  555. and compilers you'll be using with Fastgraph.
  556.  
  557.                                  Example 1-1.
  558.  
  559.       #include <fastgraf.h>
  560.       #include <stdio.h>
  561.       void main(void);
  562.  
  563.       void main()
  564.       {
  565.          int major;
  566.          int minor;
  567.  
  568.          fg_version(&major,&minor);
  569.          printf("This is version %d.%2.2d of Fastgraph.\n",major,minor);
  570.       }
  571.  
  572.      The file FASTGRAF.H contains the C function prototypes for each
  573. Fastgraph routine.  It should reside in a directory where the compiler
  574. normally searches for other .H files.  For Microsoft C and QuickC, FASTGRAF.H
  575. can reside in any of the directories specified by the INCLUDE environment
  576. variable.  For Power C, it can reside in any of the directories specified by
  577. the /i switch in the PCOPTION environment variable.
  578.  
  579.                                  Example 1-2.
  580.  
  581.           REM $INCLUDE: 'fastgraf.bi'
  582.  
  583.           DEFINT A-Z
  584.  
  585.           FGversion Major, Minor
  586.           Version! = Major + Minor*0.01
  587.  
  588.           PRINT USING "This is version #.## of Fastgraph."; Version!
  589.  
  590.           END
  591.  
  592. 6  Fastgraph User's Guide
  593.  
  594.  
  595.      You must include the DECLARE commands in the file FASTGRAF.BI at the
  596. beginning of each QuickBASIC module.  This file should reside in the
  597. directory where the compiler normally searches for other .BI files, or in any
  598. of the directories specified by the INCLUDE environment variable.  The
  599. DECLARE commands in this file automatically provide the calling convention
  600. and naming convention for each Fastgraph routine.  In addition, they relieve
  601. the QuickBASIC programmer of distinguishing arguments passed by value from
  602. those passed by reference.
  603.  
  604.                                  Example 1-3.
  605.  
  606.      $INCLUDE: '\FG\INTRFACE.FOR'
  607.  
  608.            PROGRAM MAIN
  609.  
  610.            INTEGER*2 MAJOR
  611.            INTEGER*2 MINOR
  612.  
  613.            CALL FG_VERSION (MAJOR, MINOR)
  614.  
  615.            WRITE (6,10) MAJOR, MINOR
  616.      10    FORMAT (' This is version ', I1, '.', I2.2, ' of Fastgraph.')
  617.  
  618.            STOP ' '
  619.            END
  620.  
  621.  
  622.  
  623.      You must include the INTERFACE statements in the file INTRFACE.FOR at
  624. the beginning of your program (this file should reside in the \FG directory).
  625. The INTERFACE statements in this file automatically provide the calling
  626. convention and naming convention for each Fastgraph routine.  In addition,
  627. they relieve the FORTRAN programmer of distinguishing arguments passed by
  628. value from those passed by reference.
  629.  
  630.                                  Example 1-4.
  631.  
  632.       program main;
  633.       uses fgtp;
  634.  
  635.       var
  636.         Major : integer;
  637.         Minor : integer;
  638.  
  639.       begin
  640.         fg_version(Major,Minor);
  641.         writeln('This is version ',Major,'.',Minor:2,' of Fastgraph.');
  642.       end.
  643.  
  644.  
  645.      Turbo Pascal programs that use Fastgraph or Fastgraph/Light must include
  646. a uses statement specifying the name of the Fastgraph unit, FGTP.  In
  647. addition, if the program calls any of the compiler-specific Fastgraph
  648. routines listed in Appendix D, the uses statement also must include the name
  649. of the extended Fastgraph unit, FGTPX.  The unit files must reside in a
  650. directory where Turbo Pascal normally searches for units.
  651.                                                    Chapter 1:  Introduction  7
  652.  
  653.      The following sections show the simplest compilation and linking
  654. procedures for the supported compilers.  In what follows, items enclosed in
  655. angle brackets, such as <filename>, are placeholders for parameters you must
  656. supply (the name of a file in this case).  Items enclosed in square brackets,
  657. such as [/E], are optional.
  658.  
  659.  
  660. Borland C++
  661.  
  662.      Borland C++ allows you to compile and link a program directly from the
  663. DOS command line, or from within its integrated development environment
  664. (IDE).  To use Fastgraph from the IDE, you must make sure the compiler
  665. options match one of Fastgraph's available memory models (small, medium, or
  666. large) and then create a project file that links with the corresponding
  667. Fastgraph libraries (as listed below).
  668.  
  669.      You also can compile and link a Borland C++ program from the DOS command
  670. line using the BCC command.  The format of the BCC command for compiling a
  671. program and linking it with Fastgraph is
  672.  
  673.              BCC <model> <filename> <fg_library> [<fg_extended>]
  674.  
  675. where:
  676.  
  677.      <model>        specifies the compiler memory model you'll be using.
  678.                     It must be either -ms (for the small model), -mm
  679.                     (for the medium model), or -ml (for the large
  680.                     model).
  681.  
  682.      <filename>     is the name of the file containing your
  683.                     program.  It may include a path specification.
  684.  
  685.      <fg_library>   is the name of a standard Fastgraph/Light or
  686.                     Fastgraph library.  For Fastgraph/Light, the library
  687.                     name is FGLS.LIB (for the small model), FGLM.LIB
  688.                     (for the medium model), or FGLL.LIB (for the large
  689.                     model).  For Fastgraph, the library name is FGS.LIB
  690.                     (for the small model), FGM.LIB (for the medium
  691.                     model), or FGL.LIB (for the large model).
  692.  
  693.      <fg_extended>  is the name of an optional compiler-specific
  694.                     extended Fastgraph library.  You need to specify an
  695.                     extended library name only if your program calls any
  696.                     of the Fastgraph routines listed in Appendix D.  The
  697.                     extended library name is FGTCS.LIB (for the small
  698.                     model), FGTCM.LIB (for the medium model), or
  699.                     FGTCL.LIB (for the large model).  Fastgraph/Light
  700.                     does not use extended libraries.
  701.  
  702.      For example, to compile the program 01-01.C under the medium memory
  703. model and then link it with Fastgraph, you could use the following BCC
  704. command:
  705.  
  706.                       BCC -mm 01-01.C FGM.LIB FGTCM.LIB
  707.  
  708. 8  Fastgraph User's Guide
  709.  
  710.  
  711. Although we specified the extended library name FGTCM.LIB on the command
  712. line, we didn't need to in this example because the program doesn't call any
  713. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  714. were using Fastgraph/Light instead of Fastgraph, the BCC command would be:
  715.  
  716.                            BCC -mm 01-01.C FGLM.LIB
  717.  
  718. For more information about memory models or other compilation and linking
  719. options, please refer to the Borland C++ User's Guide, published by Borland
  720. International.
  721.  
  722.  
  723. Microsoft C
  724.  
  725.      Microsoft C programs are compiled and linked by entering a CL command at
  726. the DOS command prompt.  The format of the CL command for compiling a program
  727. and linking it with Fastgraph is
  728.  
  729.         CL <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  730.  
  731. where:
  732.  
  733.      <model>        specifies the compiler memory model you'll be using.
  734.                     It must be either /AS (for the small model), /AM
  735.                     (for the medium model), or /AL (for the large
  736.                     model).
  737.  
  738.      <filename>     is the name of the file containing your
  739.                     program.  It must include the file extension
  740.                     (typically .C) and may include a path
  741.                     specification.
  742.  
  743.      <fg_library>   is the name of a standard Fastgraph/Light or
  744.                     Fastgraph library.  For Fastgraph/Light, the library
  745.                     name is FGLS (for the small model), FGLM (for the
  746.                     medium model), or FGLL (for the large model).  For
  747.                     Fastgraph, the library name is FGS (for the small
  748.                     model), FGM (for the medium model), or FGL (for the
  749.                     large model).
  750.  
  751.      <fg_extended>  is the name of an optional compiler-specific
  752.                     extended Fastgraph library.  You need to specify an
  753.                     extended library name only if your program calls any
  754.                     of the Fastgraph routines listed in Appendix D.  The
  755.                     extended library name is FGMSCS (for the small
  756.                     model), FGMSCM (for the medium model), or FGMSCL
  757.                     (for the large model).  Fastgraph/Light does not use
  758.                     extended libraries.
  759.  
  760. The /E linker option is not required but will produce a smaller .EXE file if
  761. specified.
  762.                                                    Chapter 1:  Introduction  9
  763.  
  764.      For example, to compile the program 01-01.C under the medium memory
  765. model and then link it with Fastgraph, you could use the following CL
  766. command:
  767.  
  768.                       CL /AM 01-01.C /link FGM FGMSCM /E
  769.  
  770. Although we specified the extended library name FGMSCM on the command line,
  771. we didn't need to in this example because the program doesn't call any of the
  772. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  773. Fastgraph/Light instead of Fastgraph, the CL command would be:
  774.  
  775.                          CL /AM 01-01.C /link FGLM /E
  776.  
  777. For more information about memory models or other compilation and linking
  778. options, please refer to the Microsoft C Optimizing Compiler User's Guide,
  779. published by Microsoft Corporation.
  780.  
  781.  
  782. Microsoft FORTRAN
  783.  
  784.      Microsoft FORTRAN programs are compiled and linked by entering an FL
  785. command at the DOS command prompt.  The format of the FL command for
  786. compiling a program and linking it with Fastgraph is
  787.  
  788.  FL /FPi /4I2 /4Nt <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  789.  
  790. where:
  791.  
  792.      <model>        specifies the compiler memory model you'll be using.
  793.                     It must be either /AM (for the medium model) or /AL
  794.                     (for the large model).  Microsoft FORTRAN does not
  795.                     support the small model.
  796.  
  797.      <filename>     is the name of the file containing your
  798.                     program.  It may include a path specification.
  799.  
  800.      <fg_library>   is the name of a standard Fastgraph/Light or
  801.                     Fastgraph library.  For Fastgraph/Light, the library
  802.                     name is FGLM (for the medium model) or FGLL (for the
  803.                     large model).  For Fastgraph, the library name is
  804.                     FGM (for the medium model) or FGL (for the large
  805.                     model).
  806.  
  807.      <fg_extended>  is the name of an optional compiler-specific
  808.                     extended Fastgraph library.  You need to specify an
  809.                     extended library name only if your program calls any
  810.                     of the Fastgraph routines listed in Appendix D.  The
  811.                     extended library name is FGMSFM (for the medium
  812. 10  Fastgraph User's Guide
  813.  
  814.                     model) or FGMSFL (for the large model).
  815.                     Fastgraph/Light does not use extended libraries.
  816.  
  817. The /E linker option is not required but will produce a smaller .EXE file if
  818. specified.
  819.  
  820.      For example, to compile the program 01-03.FOR under the medium memory
  821. model and then link it with Fastgraph, you could use the following FL
  822. command:
  823.  
  824.              FL /FPi /4I2 /4Nt /AM 01-03.FOR /link FGM FGMSFM /E
  825.  
  826. Although we specified the extended library name FGMSFM on the command line,
  827. we didn't need to in this example because the program doesn't call any of the
  828. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  829. Fastgraph/Light instead of Fastgraph, the FL command would be:
  830.  
  831.                 FL /FPi /4I2 /4Nt /AM 01-03.FOR /link FGLM /E
  832.  
  833. For more information about memory models or other compilation and linking
  834. options, please refer to the Microsoft FORTRAN Optimizing Compiler User's
  835. Guide, published by Microsoft Corporation.
  836.  
  837.      All the remaining example programs in the Fastgraph User's Guide are
  838. written in the C programming language.  However, when you install Fastgraph
  839. for the Microsoft FORTRAN compiler, the installation procedure copies FORTRAN
  840. versions of the example programs to the \FG\EXAMPLES directory.
  841.  
  842.  
  843. Microsoft QuickBASIC
  844.  
  845.      Microsoft QuickBASIC allows you to compile and link a program directly
  846. from the DOS command line, or from within its programming environment.  To
  847. use Fastgraph from QuickBASIC's programming environment, just specify the
  848. quick library name FGQB when starting QuickBASIC, as shown below.
  849.  
  850.                                   QB /lFGQB
  851.  
  852. If you are using Fastgraph/Light, use the library name FGLQB instead of FGQB.
  853.  
  854.      You also can compile and link a QuickBASIC program from the DOS command
  855. line using the BC and LINK commands.  The format of these commands for
  856. compiling a program and linking it with Fastgraph is
  857.  
  858.                   BC <filename>;
  859.                   LINK [/E] <object_file>,,NUL,<fg_library>
  860.  
  861. where:
  862.                                                   Chapter 1:  Introduction  11
  863.  
  864.      <filename>     is the name of the file containing your
  865.                     program.  It may include a path specification.
  866.  
  867.      <object_file>  is the name of the object file produced by the BC
  868.                     command.  By default, this will be the same as
  869.                     <filename>, but with an extension of .OBJ rather
  870.                     than .BAS.
  871.  
  872.      <fg_library>   is the name of the standard Fastgraph/Light or
  873.                     Fastgraph library.  For Fastgraph/Light, the library
  874.                     name is FGLQB.  For Fastgraph, the library name is
  875.                     FGQB.  QuickBASIC does not use extended Fastgraph
  876.                     libraries.
  877.  
  878. The /E linker option is not required but will produce a smaller .EXE file if
  879. specified.
  880.  
  881.      For example, to compile the program 01-02.BAS and then link it with
  882. Fastgraph, you could use the following commands:
  883.  
  884.                          BC 01-02.BAS;
  885.                          LINK /E 01-02.OBJ,,NUL,FGQB
  886.  
  887. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  888. be:
  889.  
  890.                          BC 01-02.BAS;
  891.                          LINK /E 01-02.OBJ,,NUL,FGLQB
  892.  
  893. For more information about other compilation and linking options, please
  894. refer to the Microsoft QuickBASIC: Programming in BASIC manual, published by
  895. Microsoft Corporation.
  896.  
  897.      All the remaining example programs in the Fastgraph User's Guide are
  898. written in the C programming language.  However, when you install Fastgraph
  899. for Microsoft QuickBASIC, the installation procedure copies QuickBASIC
  900. versions of the example programs to the \FG\EXAMPLES directory.
  901.  
  902.  
  903. Microsoft QuickC
  904.  
  905.      Microsoft QuickC allows you to compile and link a program directly from
  906. the DOS command line, or from within its programming environment.  To use
  907. Fastgraph from the QuickC programming environment, you must make sure the
  908. compiler options match one of Fastgraph's available memory models (small,
  909. medium, or large) and then create a make file that includes one or more of
  910. the corresponding Fastgraph libraries (as listed below).
  911.  
  912.      You also can compile and link a QuickC program from the DOS command line
  913. using the QCL command.  The format of the QCL command for compiling a program
  914. and linking it with Fastgraph is
  915.  
  916.         QCL <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  917.  
  918. 12  Fastgraph User's Guide
  919.  
  920.  
  921.  
  922. where:
  923.  
  924.      <model>        specifies the compiler memory model you'll be using.
  925.                     It must be either /AS (for the small model), /AM
  926.                     (for the medium model), or /AL (for the large
  927.                     model).
  928.  
  929.      <filename>     is the name of the file containing your
  930.                     program.  It must include the file extension
  931.                     (typically .C) and may include a path
  932.                     specification.
  933.  
  934.      <fg_library>   is the name of a standard Fastgraph/Light or
  935.                     Fastgraph library.  For Fastgraph/Light, the library
  936.                     name is FGLS (for the small model), FGLM (for the
  937.                     medium model), or FGLL (for the large model).  For
  938.                     Fastgraph, the library name is FGS (for the small
  939.                     model), FGM (for the medium model), or FGL (for the
  940.                     large model).
  941.  
  942.      <fg_extended>  is the name of an optional compiler-specific
  943.                     extended Fastgraph library.  You need to specify an
  944.                     extended library name only if your program calls any
  945.                     of the Fastgraph routines listed in Appendix D.  The
  946.                     extended library name is FGMSCS (for the small
  947.                     model), FGMSCM (for the medium model), or FGMSCL
  948.                     (for the large model).  Fastgraph/Light does not use
  949.                     extended libraries.
  950.  
  951. The /E linker option is not required but will produce a smaller .EXE file if
  952. specified.
  953.  
  954.      For example, to compile the program 01-01.C under the medium memory
  955. model and then link it with Fastgraph, you could use the following QCL
  956. command:
  957.  
  958.                      QCL /AM 01-01.C /link FGM FGMSCM /E
  959.  
  960. Although we specified the extended library name FGMSCM on the command line,
  961. we didn't need to in this example because the program doesn't call any of the
  962. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  963. Fastgraph/Light instead of Fastgraph, the QCL command would be:
  964.  
  965.                         QCL /AM 01-01.C /link FGLM /E
  966.  
  967. For more information about memory models or other compilation and linking
  968. options, please refer to the Microsoft QuickC Tool Kit manual, published by
  969. Microsoft Corporation.
  970.                                                   Chapter 1:  Introduction  13
  971.  
  972.  
  973. Power C
  974.  
  975.      Power C programs are compiled and linked from the DOS command line using
  976. the PC and PCL commands.  The format of these commands for compiling a
  977. program and linking it with Fastgraph is
  978.  
  979.                 PC <model> <filename>
  980.                 PCL <mix_file> ;<fg_library> [;<fg_extended>]
  981.  
  982. where:
  983.  
  984.      <model>        specifies the compiler memory model you'll be using.
  985.                     It must be either /ms (for the small model), /mm
  986.                     (for the medium model), or /ml (for the large
  987.                     model).
  988.  
  989.      <filename>     is the name of the file containing your
  990.                     program.  It may include a path specification.
  991.  
  992.      <mix_file>     is the name of the object file produced by the
  993.                     PC command.  By default, this will be the same
  994.                     as <filename>, but with an extension of .MIX
  995.                     rather than .C.
  996.  
  997.      <fg_library>   is the name of a standard Fastgraph/Light or
  998.                     Fastgraph library.  For Fastgraph/Light, the library
  999.                     name is FGLS (for the small model), FGLM (for the
  1000.                     medium model), or FGLL (for the large model).  For
  1001.                     Fastgraph, the library name is FGS (for the small
  1002.                     model), FGM (for the medium model), or FGL (for the
  1003.                     large model).
  1004.  
  1005.      <fg_extended>  is the name of an optional compiler-specific
  1006.                     extended Fastgraph library.  You need to specify an
  1007.                     extended library name only if your program calls any
  1008.                     of the Fastgraph routines listed in Appendix D.  The
  1009.                     extended library name is FGPCS (for the small
  1010.                     model), FGPCM (for the medium model), or FGPCL (for
  1011.                     the large model).  Fastgraph/Light does not use
  1012.                     extended libraries.
  1013.  
  1014.      For example, to compile the program 01-01.C under the medium memory
  1015. model and then link it with Fastgraph, you could use the following commands:
  1016.  
  1017.                           PC /mm 01-01.C
  1018.                           PCL 01-01.MIX ;FGM ;FGPCM
  1019.  
  1020. Although we specified the extended library name FGPCM on the command line, we
  1021. didn't need to in this example because the program doesn't call any of the
  1022. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  1023. Fastgraph/Light instead of Fastgraph, the commands would be:
  1024. 14  Fastgraph User's Guide
  1025.  
  1026.                              PC /mm 01-01.C
  1027.                              PCL 01-01.MIX ;FGPCM
  1028.  
  1029. For more information about memory models or other compilation and linking
  1030. options, please refer to the Power C manual, published by Mix Software, Inc.
  1031.  
  1032.  
  1033. Turbo C and Turbo C++
  1034.  
  1035.      Turbo C and Turbo C++ allow you to compile and link a program directly
  1036. from the DOS command line, or from within their integrated development
  1037. environment (IDE).  To use Fastgraph from the IDE, you must make sure the
  1038. compiler options match one of Fastgraph's available memory models (small,
  1039. medium, or large) and then create a project file that links with the
  1040. corresponding Fastgraph libraries (as listed below).
  1041.  
  1042.      You also can compile and link a Turbo C or Turbo C++ program from the
  1043. DOS command line using the TCC command.  The format of the TCC command for
  1044. compiling a program and linking it with Fastgraph is
  1045.  
  1046.              TCC <model> <filename> <fg_library> [<fg_extended>]
  1047.  
  1048. where:
  1049.  
  1050.      <model>        specifies the compiler memory model you'll be using.
  1051.                     It must be either -ms (for the small model), -mm
  1052.                     (for the medium model), or -ml (for the large
  1053.                     model).
  1054.  
  1055.      <filename>     is the name of the file containing your
  1056.                     program.  It may include a path specification.
  1057.  
  1058.      <fg_library>   is the name of a standard Fastgraph/Light or
  1059.                     Fastgraph library.  For Fastgraph/Light, the library
  1060.                     name is FGLS.LIB (for the small model), FGLM.LIB
  1061.                     (for the medium model), or FGLL.LIB (for the large
  1062.                     model).  For Fastgraph, the library name is FGS.LIB
  1063.                     (for the small model), FGM.LIB (for the medium
  1064.                     model), or FGL.LIB (for the large model).
  1065.  
  1066.      <fg_extended>  is the name of an optional compiler-specific
  1067.                     extended Fastgraph library.  You need to specify an
  1068.                     extended library name only if your program calls any
  1069.                     of the Fastgraph routines listed in Appendix D.  The
  1070.                     extended library name is FGTCS.LIB (for the small
  1071.                     model), FGTCM.LIB (for the medium model), or
  1072.                     FGTCL.LIB (for the large model).  Fastgraph/Light
  1073.                     does not use extended libraries.
  1074.  
  1075.      For example, to compile the program 01-01.C under the medium memory
  1076. model and then link it with Fastgraph, you could use the following TCC
  1077. command:
  1078.  
  1079.                       TCC -mm 01-01.C FGM.LIB FGTCM.LIB
  1080.  
  1081.                                                   Chapter 1:  Introduction  15
  1082.  
  1083.  
  1084.  
  1085. Although we specified the extended library name FGTCM.LIB on the command
  1086. line, we didn't need to in this example because the program doesn't call any
  1087. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  1088. were using Fastgraph/Light instead of Fastgraph, the TCC command would be:
  1089.  
  1090.                            TCC -mm 01-01.C FGLM.LIB
  1091.  
  1092. For more information about memory models or other compilation and linking
  1093. options, please refer to the Turbo C User's Guide and the Turbo C Reference
  1094. Guide, both published by Borland International.
  1095.  
  1096.  
  1097. Turbo Pascal
  1098.  
  1099.      Turbo Pascal allows you to compile and link a program directly from the
  1100. DOS command line with the TPC command, or from within its integrated
  1101. development environment (IDE) with the TURBO command.  To use Fastgraph from
  1102. the IDE, just start the IDE as you would for any other Pascal program, making
  1103. sure the standard unit (FGTP.TPU) and extended unit (FGTPX.TPU) reside in one
  1104. of the directories listed in the Unit Directories option.
  1105.  
  1106.      You also can compile and link a Turbo Pascal program from the DOS
  1107. command line using the TPC command.  The format of the TPC command for
  1108. compiling a program and linking it with Fastgraph is
  1109.  
  1110.                                 TPC <filename>
  1111.  
  1112. where:
  1113.  
  1114.      <filename>     is the name of the file containing your
  1115.                     program.  It may include a path specification.
  1116.  
  1117.      For example, to compile the program 01-04.PAS and then link it with
  1118. Fastgraph, you could use the following command:
  1119.  
  1120.                                 TPC 01-04.PAS
  1121.  
  1122. For more information about other compilation and linking options, please
  1123. refer to the Turbo Pascal User's Guide, published by Borland International.
  1124.  
  1125.      All the remaining example programs in the Fastgraph User's Guide are
  1126. written in the C programming language.  However, when you install Fastgraph
  1127. for Turbo Pascal, the installation procedure copies Pascal versions of the
  1128. example programs to the \FG\EXAMPLES directory.
  1129. 16  Fastgraph User's Guide
  1130.  
  1131.  
  1132. Fastgraph/Light Video Driver
  1133.  
  1134.      As mentioned earlier, running any program created with Fastgraph/Light
  1135. requires an external program called the Fastgraph/Light Video Driver.  The
  1136. video driver is a terminate and stay resident program (TSR) that provides an
  1137. interface between your program and Fastgraph.  Once loaded, the video driver
  1138. uses about 60,000 bytes of conventional memory.
  1139.  
  1140.      To load the video driver, enter the command FGDRIVER at the DOS command
  1141. prompt (assuming FGDRIVER.EXE is in the current directory, or the \FG
  1142. directory is in your DOS path specification).  The driver will display a
  1143. message indicating whether or not it loaded successfully.  After you load the
  1144. driver, just run a program created with Fastgraph/Light as you would any
  1145. other program.  If you try running a program that uses Fastgraph/Light
  1146. without first loading the video driver, the message "Fastgraph/Light video
  1147. driver not installed" will appear.
  1148.  
  1149.      You don't need to load the driver before running each program, just once
  1150. per system boot (in fact, the driver will display an "already loaded" message
  1151. if you try to load it more than once).  If you want to unload the video
  1152. driver, just enter FGDRIVER /U at the DOS command prompt.  The unload
  1153. operation will work completely only if the video driver was the last TSR
  1154. loaded.  If it wasn't the last TSR, the driver will still unload, but the
  1155. memory it uses will not be released back to DOS.
  1156.  
  1157.  
  1158. Chapter 2
  1159.  
  1160. PC and PS/2 Video Modes
  1161. 18  Fastgraph User's Guide
  1162.  
  1163.  
  1164. Overview
  1165.  
  1166.      In the PC and PS/2 worlds, the method by which information appears on
  1167. the computer's display screen is determined by the video mode currently in
  1168. effect.  The video modes have different resolutions, different character or
  1169. pixel attributes, different video memory structures, and other inherent
  1170. hardware differences.  However, you do not need an in-depth knowledge of
  1171. these video internals, because Fastgraph handles the necessary details.
  1172.  
  1173.      The PC and PS/2 video modes may be separated into two major classes:
  1174. text modes and graphics modes.  In text modes, the display screen is divided
  1175. into character cells.  There are 25 rows and either 40 or 80 columns of
  1176. cells, and in each cell we can store any of the 256 characters in the IBM PC
  1177. character set.  Each character has an associated attribute that determines
  1178. such things as its foreground color, its background color, and whether or not
  1179. the character blinks.  In graphics modes, the display screen is divided into
  1180. picture elements, or pixels.  Depending on the video mode, the number of
  1181. pixel rows ranges between 200 and 480, while the number of columns ranges
  1182. between 320 and 720.  Each pixel has an associated value that determines the
  1183. color of the pixel.  The number of character cells or pixels available is
  1184. called the resolution of the screen.
  1185.  
  1186.      The display adapter (graphics card) and the video display (monitor)
  1187. connected to it determine the video modes available on a given system.  The
  1188. following table summarizes the characteristics of the PC and PS/2 video modes
  1189. that Fastgraph supports.
  1190.  
  1191.      Mode                      No. of    Supported         Supported
  1192.     Number  Type    Resolution Colors    Adapters          Displays
  1193.  
  1194.        0    Text    40 x 25    16/8      CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1195.        1    Text    40 x 25    16/8      CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1196.        2    Text    80 x 25    16/8      CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1197.        3    Text    80 x 25    16/8      CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1198.        4  Graphics  320 x 200  4         CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1199.        5  Graphics  320 x 200  4         CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1200.        6  Graphics  640 x 200  2/16      CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1201.        7    Text    80 x 25    b/w       MDA,HGC,EGA,VGA   Mono,ECD,VGA
  1202.        9  Graphics  320 x 200  16        Tandy 1000,PCjr   RGB
  1203.       11  Graphics  720 x 348  b/w       HGC               Monochrome
  1204.       12  Graphics  320 x 200  b/w       HGC               Monochrome
  1205.       13  Graphics  320 x 200  16        EGA,VGA           RGB,ECD,VGA
  1206.       14  Graphics  640 x 200  16        EGA,VGA           RGB,ECD,VGA
  1207.       15  Graphics  640 x 350  b/w       EGA,VGA           Mono,VGA
  1208.       16  Graphics  640 x 350  16/64     EGA,VGA           ECD,VGA
  1209.       17  Graphics  640 x 480  2/256K    VGA,MCGA          VGA
  1210.       18  Graphics  640 x 480  16/256K   VGA               VGA
  1211.       19  Graphics  320 x 200  256/256K  VGA,MCGA          VGA
  1212.       20  Graphics  320 x 200  256/256K  VGA               VGA
  1213.       21  Graphics  320 x 400  256/256K  VGA               VGA
  1214.       22  Graphics  320 x 240  256/256K  VGA               VGA
  1215.       23  Graphics  320 x 480  256/256K  VGA               VGA
  1216.  
  1217.      Some notes about the format and abbreviations used in this table are in
  1218. order.  A single value in the "number of colors" column refers to the number
  1219.                                        Chapter 2:  PC and PS/2 Video Modes  19
  1220.  
  1221. of colors available in that video mode.  In text modes, a pair of numbers
  1222. such as 16/8 means each displayed character can have one of 16 foreground
  1223. colors and one of 8 background colors.  In graphics modes, a pair of numbers
  1224. such as 16/64 means 16 colors can be displayed simultaneously from a
  1225. collection, or palette, of 64.  The "b/w" listed in the monochrome modes
  1226. stands for "black and white".  Characters or pixels in these video modes do
  1227. not really have associated colors but instead have display attributes such as
  1228. blinking or different intensities.
  1229.  
  1230.      The meanings of the abbreviations in the "supported adapters" and
  1231. "supported displays" columns are:
  1232.  
  1233.      CGA       Color Graphics Adapter
  1234.      ECD       Enhanced Color Display
  1235.      EGA       Enhanced Graphics Adapter
  1236.      HGC       Hercules Graphics Card
  1237.      MCGA      Multi-Color Graphics Array
  1238.      MDA       Monochrome Display Adapter
  1239.      RGB       Red-Green-Blue Color Display
  1240.      VGA       Video Graphics Array
  1241.  
  1242. The use of the term "VGA" in the "supported display" column refers to any
  1243. analog display, such as a VGA, Super VGA (SVGA), or Multisync monitor.
  1244.  
  1245.      The IBM PS/2 family does not have an adapter and display combination per
  1246. se.  Instead, the video hardware used in these systems is called the video
  1247. subsystem.  The Model 25 and Model 30 have an MCGA-based video subsystem,
  1248. while other models have a VGA-based video subsystem.
  1249.  
  1250.      This rest of this chapter will provide an overview of the most important
  1251. features and restrictions of each video mode.  The first section will discuss
  1252. the text modes, while the following section will discuss the graphics modes.
  1253.  
  1254.  
  1255. Text Modes
  1256.  
  1257.      There are five text video modes in the IBM PC and PS/2 family.  Four of
  1258. these modes (0, 1, 2, and 3) are designed for color displays, while the
  1259. remaining mode (7) is designed for monochrome displays.  All text modes were
  1260. introduced with the original IBM PC.
  1261.  
  1262.      In text modes, the screen is divided into character cells.  There are
  1263. two bytes of video memory associated with each character cell -- one byte for
  1264. the character's ASCII value, and another for the character's display
  1265. attribute.  The amount of video memory required to store one screen of
  1266. information (called a video page) is thus
  1267.  
  1268.                     number_of_columns x number_of_rows x 2
  1269.  
  1270. All text modes use 25 rows, so for the 40-column modes (0 and 1) the size of
  1271. a video page is 2,000 bytes, and for the 80-column modes (2, 3, and 7) the
  1272. size of a video page is 4,000 bytes.
  1273. 20  Fastgraph User's Guide
  1274.  
  1275.       Mode                No. of   Supported         Supported
  1276.      Number  Resolution   Colors   Adapters          Displays
  1277.  
  1278.        0     40 x 25      16/8     CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1279.        1     40 x 25      16/8     CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1280.        2     80 x 25      16/8     CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1281.        3     80 x 25      16/8     CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1282.        7     80 x 25      b/w      MDA,HGC,EGA,VGA   Monochrome,ECD,VGA
  1283.  
  1284.      The remainder of this section will describe the text video modes in more
  1285. detail.
  1286.  
  1287. Mode 0
  1288.  
  1289.      Mode 0 is a 40-column by 25-row color text mode.  It is often called a
  1290. colorless mode since it was designed to be used with composite or television
  1291. monitors (as opposed to RGB monitors).  When used with these types of
  1292. monitors, the available 16 "colors" appear as distinct shades of gray.  When
  1293. used with an RGB monitor, mode 0 is identical in all respects to mode 1.  The
  1294. use of composite or television monitors as PC video displays has virtually
  1295. disappeared today.  As a result, mode 0 is used infrequently.
  1296.  
  1297. Mode 1
  1298.  
  1299.      Mode 1 is a 40-column by 25-row color text mode.  It is supported across
  1300. all video adapter and color display combinations in the PC and PS/2 families.
  1301. Characters displayed in mode 1 have an associated display attribute that
  1302. defines the character's foreground color, its background color, and whether
  1303. or not it blinks.  Sixteen foreground colors and eight background colors are
  1304. available.
  1305.  
  1306. Mode 2
  1307.  
  1308.      Mode 2 is an 80-column by 25-row color text mode.  Like mode 0, it is
  1309. often called a colorless mode since it was designed to be used with composite
  1310. or television monitors (as opposed to RGB monitors).  When used with these
  1311. types of monitors, the available 16 "colors" appear as distinct shades of
  1312. gray.  When used with an RGB monitor, mode 2 is identical in all respects to
  1313. mode 3.  The use of composite or television monitors as PC video displays has
  1314. virtually disappeared today.  As a result, mode 2 is used infrequently.
  1315.  
  1316. Mode 3
  1317.  
  1318.      Mode 3 is an 80-column by 25-row color text mode.  It is the default
  1319. video mode for systems that use any type of color display.  This mode is
  1320. supported across all video adapter and color display combinations in the PC
  1321. and PS/2 families.  Characters displayed in mode 3 have an associated display
  1322. attribute that defines the character's foreground color, its background
  1323. color, and whether or not it blinks.  Sixteen foreground colors and eight
  1324. background colors are available.
  1325.  
  1326. Mode 7
  1327.  
  1328.      Mode 7 is the 80-column by 25-row monochrome text mode.  It is the
  1329. default video mode for systems that use a monochrome display.  To use this
  1330. mode, you must have a Monochrome Display Adapter (MDA), Hercules Graphics
  1331. Card (HGC), or an Enhanced Graphics Adapter (EGA) connected to a monochrome
  1332.                                        Chapter 2:  PC and PS/2 Video Modes  21
  1333.  
  1334. display.  Most VGA display adapters also provide an emulation mode that
  1335. allows you to use mode 7 with analog displays.  Characters displayed in mode
  1336. 7 have an associated display attribute that defines whether the character is
  1337. invisible, normal, bold, underlined, reversed, blinking, or a combination of
  1338. these.
  1339.  
  1340.  
  1341. Graphics Modes
  1342.  
  1343.      There are 13 standard graphics video modes available in the IBM PC and
  1344. PS/2 family.  Fastgraph provides support for 11 of the 13 modes (modes 8 and
  1345. 10, which are specific to the PCjr and Tandy 1000 systems, are not
  1346. supported).  In addition to these 13 modes, Fastgraph supports two video
  1347. modes for the Hercules Graphics Card (modes 11 and 12) and four extended VGA
  1348. modes (modes 20 through 23).  The following sections discuss the graphics
  1349. modes in more detail.  The discussions include an overview of video memory
  1350. organization in each mode, but you don't need a knowledge of this subject to
  1351. use Fastgraph.
  1352.  
  1353.  
  1354. CGA Graphics Modes
  1355.  
  1356.      Modes 4, 5, and 6 are designed to be used with the Color Graphics
  1357. Adapter (CGA) and for this reason are called the native CGA modes.  They were
  1358. the only graphics modes available with the original IBM PC.  Newer graphics
  1359. adapters (EGA, VGA, and MCGA) can emulate the CGA, which means that the CGA
  1360. graphics modes are available on any PC or PS/2 system equipped with a color
  1361. display.
  1362.  
  1363.  
  1364.          Mode                No. of   Supported         Supported
  1365.         Number  Resolution   Colors   Adapters          Displays
  1366.  
  1367.           4     320 x 200    4        CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1368.           5     320 x 200    4        CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1369.           6     640 x 200    2/16     CGA,EGA,VGA,MCGA  RGB,ECD,VGA
  1370.  
  1371.  
  1372. Mode 4
  1373.  
  1374.      Mode 4 is a CGA graphics mode with a resolution of 320 horizontal pixels
  1375. by 200 vertical pixels.  Each pixel can assume one of four colors (the
  1376. available colors are determined by which one of six palettes has been
  1377. selected), so each pixel requires two bits of video memory.  This means that
  1378. each byte of video memory represents four pixels.
  1379.  
  1380. Mode 5
  1381.  
  1382.      Mode 5 is the colorless analog of mode 4.  It was designed to be used
  1383. with composite or television monitors (as opposed to RGB monitors).  When
  1384. used with these types of monitors, the four colors appear as distinct shades
  1385. of gray.  When used with an RGB monitor, mode 5 is essentially identical to
  1386. mode 4.  The use of composite or television monitors as PC video displays has
  1387. virtually disappeared today.  As a result, mode 5 is used infrequently.
  1388. 22  Fastgraph User's Guide
  1389.  
  1390. Mode 6
  1391.  
  1392.      Mode 6 is a CGA graphics mode with a resolution of 640 horizontal pixels
  1393. by 200 vertical pixels.  Each pixel can assume two states -- on or off.  The
  1394. color in which the "on" pixels appear can be selected from a palette of 16
  1395. available colors.  Each pixel thus requires one bit of video memory, which
  1396. means that each byte of video memory represents eight pixels.
  1397.  
  1398.  
  1399. Tandy 1000 and PCjr Graphics Modes
  1400.  
  1401.      Modes 8, 9, and 10 are only available on the PCjr and Tandy 1000 series
  1402. computers (these systems also support modes 4, 5, and 6).  Modes 8 and 10 are
  1403. not widely used, and for this reason Fastgraph does not support them.
  1404.  
  1405.  
  1406.              Mode                No. of   Supported         Supported
  1407.             Number  Resolution   Colors   Adapters          Displays
  1408.  
  1409.               8     160 x 200    16       Tandy 1000,PCjr   RGB
  1410.               9     320 x 200    16       Tandy 1000,PCjr   RGB
  1411.               10    640 x 200    4        Tandy 1000,PCjr   RGB
  1412.  
  1413.  
  1414. Mode 9
  1415.  
  1416.      Mode 9 is a Tandy 1000 and PCjr graphics mode with a resolution of 320
  1417. horizontal pixels by 200 vertical pixels.  Each pixel can assume one of 16
  1418. colors, so each pixel requires four bits of video memory.  This means that
  1419. each byte of video memory represents two pixels.  The Tandy 1000 and PCjr use
  1420. standard random-access memory (RAM) as video memory.
  1421.  
  1422.  
  1423. Hercules Graphics Modes
  1424.  
  1425.      Modes 11 and 12 are used with the Hercules Graphics Card (HGC) and a
  1426. monochrome display.  As such, they are not true IBM video modes, but because
  1427. of the popularity of the HGC, Fastgraph provides support for this adapter.
  1428. IBM has not defined video modes with numbers 11 and 12.  Should they choose
  1429. to do so in the future, Fastgraph's Hercules video mode numbers would likely
  1430. change.
  1431.  
  1432.  
  1433.           Mode                No. of   Supported         Supported
  1434.          Number  Resolution   Colors   Adapters          Displays
  1435.  
  1436.            11    720 x 348    b/w      HGC               Monochrome
  1437.            12    320 x 200    b/w      HGC               Monochrome
  1438.                                        Chapter 2:  PC and PS/2 Video Modes  23
  1439.  
  1440. Mode 11
  1441.  
  1442.      Mode 11 is a true Hercules graphics mode with a resolution of 720
  1443. horizontal pixels by 348 vertical pixels.  Each pixel can assume two
  1444. states -- on or off.  Each pixel thus requires one bit of video memory, which
  1445. means that each byte of video memory represents eight pixels.
  1446.  
  1447. Mode 12
  1448.  
  1449.      Mode 12 is a software-simulated Hercules graphics mode with an effective
  1450. resolution of 320 horizontal pixels by 200 vertical pixels.  Its purpose is
  1451. to provide a resolution that is available with all other graphics display
  1452. adapters.
  1453.  
  1454.      This mode converts all coordinates from the 320 by 200 space (called
  1455. virtual coordinates) into the 720 by 348 coordinate system (called physical
  1456. coordinates).  It does this by using two physical pixels for each virtual
  1457. pixel and scan doubling the odd-numbered virtual rows.  Finally, offsets are
  1458. added to the resulting physical coordinates to center the image area on the
  1459. display.  This creates an image area bounded horizontally by the physical
  1460. coordinates 40 and 679 and vertically by the physical coordinates 24 and 323.
  1461.  
  1462.  
  1463. EGA Graphics Modes
  1464.  
  1465.      Modes 13 through 16 were introduced with the Enhanced Graphics Adapter
  1466. (EGA) and for this reason are called the native EGA modes.  The VGA also
  1467. provides support for these modes, but the MCGA does not.  The original IBM
  1468. EGA only contained 64K bytes of video memory, but memory could be added in
  1469. 64K increments to fully populate the adapter with 256K bytes of video memory.
  1470. As other manufacturers developed EGA cards, they generally included 256K
  1471. bytes of video memory as a standard feature.
  1472.  
  1473.  
  1474.         Mode                No. of   Supported         Supported
  1475.        Number  Resolution   Colors   Adapters          Displays
  1476.  
  1477.          13    320 x 200    16       EGA,VGA           RGB,ECD,VGA
  1478.          14    640 x 200    16       EGA,VGA           RGB,ECD,VGA
  1479.          15    640 x 350    b/w      EGA,VGA           Monochrome,VGA
  1480.          16    640 x 350    16/64    EGA,VGA           ECD,VGA
  1481.  
  1482.  
  1483. Mode 13
  1484.  
  1485.      Mode 13 is an EGA graphics mode with a resolution of 320 horizontal
  1486. pixels by 200 vertical pixels.  Each pixel can assume one of 16 colors, so
  1487. each pixel requires four bits of video memory.  In this mode, video memory is
  1488. organized as four bit planes.  Each video memory address actually references
  1489. four bytes, one in each plane.  Put another way, each video memory byte
  1490. references eight pixels, stored one bit per plane.
  1491. 24  Fastgraph User's Guide
  1492.  
  1493. Mode 14
  1494.  
  1495.      Mode 14 is an EGA graphics mode with a resolution of 640 horizontal
  1496. pixels by 200 vertical pixels.  Each pixel can assume one of 16 colors, so
  1497. each pixel requires four bits of video memory.  In this mode, video memory is
  1498. organized as four bit planes.  Each video memory address actually references
  1499. four bytes, one in each plane.  Put another way, each video memory byte
  1500. references eight pixels, stored one bit per plane.
  1501.  
  1502. Mode 15
  1503.  
  1504.      Mode 15 is an EGA monochrome graphics mode with a resolution of 640
  1505. horizontal pixels by 350 vertical pixels.  Each pixel can assume one of 4
  1506. display attributes, so each pixel requires two bits of video memory.  In this
  1507. mode, video memory is organized as four bit planes, two of which are
  1508. disabled.  Each video memory address actually references two bytes, one in
  1509. each enabled plane.  Put another way, each video memory byte references eight
  1510. pixels, stored one bit per plane.
  1511.  
  1512. Mode 16
  1513.  
  1514.      Mode 16 is an EGA graphics mode with a resolution of 640 horizontal
  1515. pixels by 350 vertical pixels.(1)  Each pixel can assume one of 16 colors
  1516. (the 16 colors can be selected from a palette of 64 colors), so each pixel
  1517. requires four bits of video memory.  In this mode, video memory is organized
  1518. as four bit planes.  Each video memory address actually references four
  1519. bytes, one in each plane.  Put another way, each video memory byte references
  1520. eight pixels, stored one bit per plane.
  1521.  
  1522.  
  1523. VGA and MCGA Graphics Modes
  1524.  
  1525.      Modes 17, 18, and 19 were introduced with the MCGA and VGA video
  1526. subsystems of the IBM PS/2 computers.  Since the introduction of the PS/2,
  1527. other manufacturers have developed VGA cards that can be used with the PC
  1528. family.  The VGA supports all three of these modes, but the MCGA does not
  1529. support mode 18.  Modes 17 and 18 are called native VGA modes.
  1530.  
  1531.      Modes 20 through 23 are the extended VGA graphics modes.  Although these
  1532. video modes are not standard VGA modes, they will work on any VGA system.
  1533. Mode 20 is a special VGA version of mode 19, while mode 21 uses scan doubling
  1534. to achieve a 400-line display.  Mode 22 is the so-called "mode X" and is
  1535. appealing because it has a 1:1 aspect ratio.  Mode 23 is identical to mode
  1536. 22, but it uses scan doubling to achieve a 480-line display.  Should IBM
  1537. define video modes numbered 20 through 23 in the future, Fastgraph's numbers
  1538. for these video modes would likely change.
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545. ____________________
  1546.  
  1547.      (1) In mode 16, the video page size actually is 640 x 400 pixels, though
  1548. the screen resolution is 640 x 350.  The final 50 pixel rows are not displayed
  1549. but are available for off-screen storage.
  1550.                                        Chapter 2:  PC and PS/2 Video Modes  25
  1551.  
  1552.  
  1553.            Mode                No. of    Supported        Supported
  1554.           Number  Resolution   Colors    Adapters         Displays
  1555.  
  1556.             17    640 x 480    2/256K    VGA,MCGA         VGA
  1557.             18    640 x 480    16/256K   VGA              VGA
  1558.             19    320 x 200    256/256K  VGA,MCGA         VGA
  1559.             20    320 x 200    256/256K  VGA              VGA
  1560.             21    320 x 400    256/256K  VGA              VGA
  1561.             22    320 x 240    256/256K  VGA              VGA
  1562.             23    320 x 480    256/256K  VGA              VGA
  1563.  
  1564. Mode 17
  1565.  
  1566.      Mode 17 is a VGA and MCGA graphics mode with a resolution of 640
  1567. horizontal pixels by 480 vertical pixels.  Each pixel can assume two
  1568. states -- on or off.  The color in which the "on" and "off" pixels appear can
  1569. be selected from a palette of 262,144 available colors.  Each pixel thus
  1570. requires one bit of video memory, which means that each byte of video memory
  1571. represents eight pixels.  On VGA systems, video memory is organized as four
  1572. bit planes, and mode 17 is implemented by enabling one of these planes.
  1573.  
  1574. Mode 18
  1575.  
  1576.      Mode 18 is a native VGA graphics mode with a resolution of 640
  1577. horizontal pixels by 480 vertical pixels.  Each pixel can assume one of 16
  1578. colors (the 16 colors can be selected from a palette of 262,144 colors), so
  1579. each pixel requires four bits of video memory.  In this mode, video memory is
  1580. organized as four bit planes.  Each video memory address actually references
  1581. four bytes, one in each plane.  Put another way, each video memory byte
  1582. references eight pixels, stored one bit per plane.
  1583.  
  1584. Mode 19
  1585.  
  1586.      Mode 19 is a VGA and MCGA graphics mode with a resolution of 320
  1587. horizontal pixels by 200 vertical pixels.  Each pixel can assume one of 256
  1588. colors (the 256 colors can be selected from a palette of 262,144 colors), so
  1589. each pixel requires eight bits of video memory.  This means that each byte of
  1590. video memory represents one pixel.
  1591.  
  1592. Mode 20
  1593.  
  1594.      Mode 20 is a VGA graphics mode with a resolution of 320 horizontal
  1595. pixels by 200 vertical pixels.  Each pixel can assume one of 256 colors (the
  1596. 256 colors can be selected from a palette of 262,144 colors), so each pixel
  1597. requires eight bits of video memory.  This means that each byte of video
  1598. memory represents one pixel.  This mode offers the same resolution and number
  1599. of colors as mode 19, but its video memory is organized as a series of four
  1600. bit planes.  Every fourth pixel is stored in the same plane (that is, a pixel
  1601. whose horizontal coordinate is x resides in plane x mod 4).
  1602.  
  1603. Mode 21
  1604.  
  1605.      Mode 21 is a VGA color graphics mode with a resolution of 320 horizontal
  1606. pixels by 400 vertical pixels.  Except for the resolution, its video memory
  1607. organization is identical to mode 20.
  1608. 26  Fastgraph User's Guide
  1609.  
  1610. Mode 22
  1611.  
  1612.      Mode 22 is a VGA color graphics mode with a resolution of 320 horizontal
  1613. pixels by 240 vertical pixels.  This is the so-called "mode X" described by
  1614. Michael Abrash in Dr. Dobb's Journal.  Except for the resolution, its video
  1615. memory organization is identical to mode 20.
  1616.  
  1617. Mode 23
  1618.  
  1619.      Mode 23 is a VGA color graphics mode with a resolution of 320 horizontal
  1620. pixels by 480 vertical pixels.  Except for the resolution, its video memory
  1621. organization is identical to mode 20.
  1622.  
  1623.  
  1624. Chapter 3
  1625.  
  1626. Initializing the
  1627. Video Environment
  1628. 28  Fastgraph User's Guide
  1629.  
  1630.  
  1631. Overview
  1632.  
  1633.      Before Fastgraph can perform any text or graphics video operations, you
  1634. must select a video mode in which your program will run.  An important part
  1635. of this selection depends on whether your program will run in a text mode, a
  1636. graphics mode, or both.  This chapter discusses the necessary video
  1637. initialization for each case.
  1638.  
  1639.  
  1640. Establishing a Text Mode
  1641.  
  1642.      When you write a program that only uses text modes, you must determine
  1643. if the program will run on monochrome systems, color systems, or both.  In
  1644. general, there is no reason to exclude one type of system, because the
  1645. additional programming required to support both is rather trivial.
  1646.  
  1647.      The Fastgraph routine fg_setmode establishes a video mode and
  1648. initializes Fastgraph's internal parameters for that mode.  This routine has
  1649. a single integer argument whose value is a video mode number between 0 and
  1650. 23.  Its value can also be -1, which tells Fastgraph to use the current video
  1651. mode.  Specifying an fg_setmode argument of -1 is often useful in programs
  1652. that only use text video modes.
  1653.  
  1654.      When you establish a text video mode, the ROM BIOS text cursor is made
  1655. visible, and this is often undesirable.  The Fastgraph routine fg_cursor
  1656. controls the visibility of the text cursor.  The fg_cursor routine has a
  1657. single integer argument that specifies the cursor visibility.  If its value
  1658. is 0, the cursor is made invisible; if its value is 1, the cursor is made
  1659. visible.
  1660.  
  1661.      At this point, an example may help to clarify things.  The following
  1662. program shows how to initialize Fastgraph for the 80-column color text mode
  1663. (mode 3) and turn off the text mode cursor.  It uses two Fastgraph routines
  1664. that we have not yet discussed, fg_setcolor and fg_text.  These routines will
  1665. be discussed in later sections of this document.  For now, it should suffice
  1666. to know the call to fg_setcolor makes subsequent text appear in bright white,
  1667. and the call to fg_text displays the characters passed to it.
  1668.  
  1669.                                  Example 3-1.
  1670.  
  1671.                        #include <fastgraf.h>
  1672.                        void main(void);
  1673.  
  1674.                        void main()
  1675.                        {
  1676.                           fg_setmode(3);
  1677.                           fg_cursor(0);
  1678.  
  1679.                           fg_setcolor(15);
  1680.                           fg_text("Hello, world.",13);
  1681.                        }
  1682.  
  1683.      If you run example 3-1, notice the text displayed by the program appears
  1684. in the upper left corner of the screen.  On the line below this, the DOS
  1685. prompt appears, waiting for your next DOS command.  Furthermore, if your
  1686. system uses the ANSI.SYS driver to set screen attributes (such as with
  1687.                             Chapter 3:  Initializing the Video Environment  29
  1688.  
  1689. Norton's SA program), you should also notice only the DOS prompt appears in
  1690. the colors defined by the screen attributes -- the rest of the screen is
  1691. blank.
  1692.  
  1693.      A more graceful return to DOS is needed.  In example 3-2, we'll use the
  1694. Fastgraph routine fg_reset.  This routine erases the screen, and if the
  1695. ANSI.SYS driver is loaded, fg_reset also restores any previously set screen
  1696. attributes.  We've also included a call to the Fastgraph routine fg_waitkey
  1697. to wait for a keystroke before exiting.  If we didn't do this, we would never
  1698. see the program's output.
  1699.  
  1700.                                  Example 3-2.
  1701.  
  1702.                        #include <fastgraf.h>
  1703.                        void main(void);
  1704.  
  1705.                        void main()
  1706.                        {
  1707.                           fg_setmode(3);
  1708.                           fg_cursor(0);
  1709.  
  1710.                           fg_setcolor(15);
  1711.                           fg_text("Hello, world.",13);
  1712.                           fg_waitkey();
  1713.  
  1714.                           fg_reset();
  1715.                        }
  1716.  
  1717.      Since examples 3-1 and 3-2 specifically used video mode 3, they would
  1718. not work on a monochrome system.  Ideally, we would like to use fg_setmode(3)
  1719. for color systems and fg_setmode(7) for monochrome systems.  To do this, we
  1720. need a way to determine whether the program is being run on a color system or
  1721. on a monochrome system.  The next example illustrates an easy way to
  1722. accomplish this.
  1723.  
  1724.      Example 3-3 uses the Fastgraph routine fg_testmode to determine if the
  1725. user's system will support the video mode number specified as its first
  1726. argument (the second argument is the number of video pages required, which
  1727. will be 1 for all examples in this section).  The fg_testmode routine returns
  1728. a value of 1 (as its function value) if the requested video mode can be used,
  1729. and it returns 0 if not.  The program first sees if an 80-column color text
  1730. mode is available (mode 3), and if so, it selects that mode.  If the color
  1731. mode is not available, it checks if the monochrome text mode is available
  1732. (mode 7), and if so, it chooses the monochrome mode.  If neither mode is
  1733. available, then the program assumes the user's system has a 40-column
  1734. display, issues a message indicating the program requires an 80-column
  1735. display, and then exits.
  1736.  
  1737.                                  Example 3-3.
  1738.  
  1739.                    #include <fastgraf.h>
  1740.                    #include <stdio.h>
  1741.                    #include <stdlib.h>
  1742.                    void main(void);
  1743.  
  1744.                    void main()
  1745.  
  1746. 30  Fastgraph User's Guide
  1747.  
  1748.                    {
  1749.                       int old_mode;
  1750.  
  1751.                       old_mode = fg_getmode();
  1752.  
  1753.                       if (fg_testmode(3,1))
  1754.                          fg_setmode(3);
  1755.                       else if (fg_testmode(7,1))
  1756.                          fg_setmode(7);
  1757.                       else {
  1758.                          printf("This program requires\n");
  1759.                          printf("an 80-column display.\n");
  1760.                          exit(1);
  1761.                          }
  1762.  
  1763.                       fg_cursor(0);
  1764.  
  1765.                       fg_setcolor(15);
  1766.                       fg_text("Hello, world.",13);
  1767.                       fg_waitkey();
  1768.  
  1769.                       fg_setmode(old_mode);
  1770.                       fg_reset();
  1771.                    }
  1772.  
  1773.  
  1774.      Example 3-3 also illustrates another useful procedure.  It is
  1775. recommended, especially in graphics modes, to restore the original video mode
  1776. and screen attributes before a program returns to DOS.  We've already seen
  1777. how the fg_reset routine restores the screen attributes, but how do we
  1778. restore the original video mode?  The Fastgraph routine fg_getmode returns
  1779. the current video mode as its function value.  If we call fg_getmode before
  1780. calling fg_setmode, we can use the return value from fg_getmode and again
  1781. call fg_setmode before the program exits.
  1782.  
  1783.      You also can use another Fastgraph routine, fg_bestmode, to determine if
  1784. a video mode with a specific resolution is available on the user's system.
  1785. The fg_bestmode routine requires three integer arguments:  a horizontal
  1786. resolution, a vertical resolution, and the number of video pages required.
  1787. As its function value, fg_bestmode returns the video mode number that offers
  1788. the most capabilities for the resolution and number of pages requested.  It
  1789. returns a value of -1 if no available video mode offers the requested
  1790. criteria.
  1791.  
  1792.      For example, if we require an 80 by 25 text mode, we can use the
  1793. function call fg_bestmode(80,25,1) to pick the "best" video mode available
  1794. that offers this capability.  In text modes, the term best means to give
  1795. preference to a color text mode over a monochrome text mode.  Example 3-4
  1796. performs the same function as example 3-3, but it uses fg_bestmode rather
  1797. than fg_testmode.
  1798.  
  1799.                                  Example 3-4.
  1800.  
  1801.                    #include <fastgraf.h>
  1802.                    #include <stdio.h>
  1803.                    #include <stdlib.h>
  1804.  
  1805.                             Chapter 3:  Initializing the Video Environment  31
  1806.  
  1807.                    void main(void);
  1808.  
  1809.                    void main()
  1810.                    {
  1811.                       int old_mode;
  1812.                       int new_mode;
  1813.  
  1814.                       old_mode = fg_getmode();
  1815.                       new_mode = fg_bestmode(80,25,1);
  1816.                       if (new_mode < 0) {
  1817.                          printf("This program requires\n");
  1818.                          printf("an 80-column display.\n");
  1819.                          exit(1);
  1820.                          }
  1821.  
  1822.                       fg_setmode(new_mode);
  1823.                       fg_cursor(0);
  1824.  
  1825.                       fg_setcolor(15);
  1826.                       fg_text("Hello, world.",13);
  1827.                       fg_waitkey();
  1828.  
  1829.                       fg_setmode(old_mode);
  1830.                       fg_reset();
  1831.                    }
  1832.  
  1833. 43-line and 50-line Text Modes
  1834.  
  1835.      When using an 80-column text mode on a system equipped with an EGA, VGA,
  1836. or MCGA video display and adapter, you can extend the screen size from 25
  1837. lines to 43 or 50 lines.  While all systems offer 25-line text modes, EGA
  1838. systems also offer 43-line modes, MCGA systems also offer 50-line modes, and
  1839. VGA systems offer both 43-line and 50-line modes.  The 43-line mode is not
  1840. available on EGA systems equipped with an RGB display.  If you extend the
  1841. screen size to 43 or 50 lines, the physical character size is reduced
  1842. proportionally so all lines appear on the screen.
  1843.  
  1844.      The fg_setlines routine defines the number of text rows per screen.  It
  1845. has a single integer argument whose value must be 25, 43, or 50.  If you pass
  1846. any other value to fg_setlines, or pass a value not supported by the host
  1847. system's video configuration, fg_setlines does nothing.  In addition, calling
  1848. fg_setlines makes the text cursor visible.  Another Fastgraph routine,
  1849. fg_getlines, returns as its function value the number of text rows currently
  1850. in effect.  You also can use fg_getlines in graphics video modes.
  1851.  
  1852.      Example 3-5 illustrates the use of the fg_setlines and fg_getlines
  1853. routines.  The program first establishes the 80-column color text mode (this
  1854. sets the screen size to its 25-line default) and makes the text cursor
  1855. invisible.  It then displays the words "first line" in the upper left corner
  1856. of the screen.  Next, the program checks if an EGA with enhanced display is
  1857. available, and if so, changes the screen to 43 lines (video mode 16 is only
  1858. available on EGA systems equipped with an enhanced display).  Next, the
  1859. program checks if a VGA or MCGA is available, and if so changes the screen to
  1860. 50 lines (video mode 17 is only available on VGA and MCGA systems).  Finally,
  1861. the program restores the original video mode, restores the number of lines
  1862. per screen to its original setting, and restores the original screen
  1863. attributes before exiting.
  1864. 32  Fastgraph User's Guide
  1865.  
  1866.                                  Example 3-5.
  1867.  
  1868.                         #include <fastgraf.h>
  1869.                         void main(void);
  1870.  
  1871.                         void main()
  1872.                         {
  1873.                            int lines;
  1874.                            int old_lines;
  1875.                            int old_mode;
  1876.  
  1877.                            old_lines = fg_getlines();
  1878.                            old_mode = fg_getmode();
  1879.                            fg_setmode(3);
  1880.                            fg_cursor(0);
  1881.  
  1882.                            fg_setcolor(15);
  1883.                            fg_text("first line",10);
  1884.                            fg_waitkey();
  1885.  
  1886.                            if (fg_testmode(16,0)) {
  1887.                               fg_setlines(43);
  1888.                               fg_cursor(0);
  1889.                               fg_waitkey();
  1890.                               }
  1891.  
  1892.                            if (fg_testmode(17,0)) {
  1893.                               fg_setlines(50);
  1894.                               fg_cursor(0);
  1895.                               fg_waitkey();
  1896.                               }
  1897.  
  1898.                            fg_setmode(old_mode);
  1899.                            fg_setlines(old_lines);
  1900.                            fg_reset();
  1901.                         }
  1902.  
  1903.  
  1904.  
  1905. Establishing a Graphics Mode
  1906.  
  1907.      The steps for establishing a graphics mode are similar to establishing a
  1908. text mode.  However, there are more restrictions since some systems may not
  1909. support all the graphics video modes.  For example, a program could not run
  1910. in mode 13 on a CGA system, nor could a program run in mode 9 on anything
  1911. except a Tandy 1000 or PCjr system.
  1912.  
  1913.      Example 3-6 shows one way to write an EGA-specific program.  The program
  1914. in this example uses mode 16, the 640 x 350 EGA mode that requires an
  1915. Enhanced Color Display (ECD).  It uses the Fastgraph routine fg_egacheck to
  1916. determine if an EGA and ECD are present.  The fg_egacheck routine returns a
  1917. value of 0 if an EGA is not found, or if there is an EGA but no ECD.  If an
  1918. EGA and ECD are found, it returns a positive integer indicating the number of
  1919. 64K-byte increments of video memory on the EGA.  Since mode 16 requires
  1920. 112,000 bytes of video memory for a single video page, there must be at least
  1921. 128K bytes of video memory on the EGA to run this program.  Hence, we must be
  1922. sure that fg_egacheck returns a value of at least 2.
  1923.                             Chapter 3:  Initializing the Video Environment  33
  1924.  
  1925.                                  Example 3-6.
  1926.  
  1927.     #include <fastgraf.h>
  1928.     #include <stdio.h>
  1929.     #include <stdlib.h>
  1930.     void main(void);
  1931.  
  1932.     void main()
  1933.     {
  1934.        int mode;
  1935.  
  1936.        if (fg_egacheck() < 2) {
  1937.           printf("This program requires an Enhanced Graphics Adapter\n");
  1938.           printf("(EGA) and an Enhanced Color Display (ECD).\n");
  1939.           exit(1);
  1940.           }
  1941.  
  1942.        mode = fg_getmode();
  1943.        fg_setmode(16);
  1944.  
  1945.        fg_setcolor(15);
  1946.        fg_text("Hello, world.",13);
  1947.        fg_waitkey();
  1948.  
  1949.        fg_setmode(mode);
  1950.        fg_reset();
  1951.     }
  1952.  
  1953.  
  1954.  
  1955.      For graphics programs, it may suffice to write a program to run in a
  1956. specific video mode, but it is often more desirable to write a program that
  1957. will run in any of several video modes.  This is especially true for
  1958. commercial products, since they should run on as many different video
  1959. configurations as possible.
  1960.  
  1961.      Fastgraph includes a routine named fg_automode that determines the
  1962. graphics video mode that offers the most functionality for the user's video
  1963. hardware configuration.  For example, the Tandy 1000 series computers support
  1964. all three CGA modes (4, 5, and 6) and the 320 by 200 16-color Tandy 1000 mode
  1965. (9).  Of these modes, mode 9 offers the most features from a graphics
  1966. standpoint, so fg_automode will return a value of 9 when run on a Tandy 1000
  1967. computer.  The following table summarizes the video mode numbers returned by
  1968. fg_automode for given adapter-display combinations.
  1969.  
  1970.                                ------- display -------
  1971.                       adapter   mono   RGB   ECD   VGA
  1972.  
  1973.                         MDA       7     0     7     7
  1974.                         HGC      11     0     0    11
  1975.                         CGA       0     4     0     0
  1976.                         EGA      15    13    16     0
  1977.                         VGA      17    17    17    18
  1978.                        MCGA      17    17    17    19
  1979.                       Tandy       7     9     0     0
  1980.                        PCjr       7     9     0     0
  1981.  
  1982. 34  Fastgraph User's Guide
  1983.  
  1984.  
  1985.      Example 3-7 shows how to use fg_automode to determine the "best"
  1986. graphics mode for the user's video hardware.  In graphics modes, the term
  1987. best means the highest resolution, followed by the number of available
  1988. colors.  The program displays a message that includes the selected video mode
  1989. number.
  1990.  
  1991.                                  Example 3-7.
  1992.  
  1993.                     #include <fastgraf.h>
  1994.                     #include <stdio.h>
  1995.                     void main(void);
  1996.  
  1997.                     void main()
  1998.                     {
  1999.                        int old_mode;
  2000.                        int new_mode;
  2001.                        char string[4];
  2002.  
  2003.                        old_mode = fg_getmode();
  2004.                        new_mode = fg_automode();
  2005.                        fg_setmode(new_mode);
  2006.  
  2007.                        fg_setcolor(15);
  2008.                        fg_text("I'm running in mode ",20);
  2009.                        sprintf(string,"%d.",new_mode);
  2010.                        fg_text(string,3);
  2011.                        fg_waitkey();
  2012.  
  2013.                        fg_setmode(old_mode);
  2014.                        fg_reset();
  2015.                     }
  2016.  
  2017.      For simple programs such as example 3-7, different screen resolutions
  2018. may not be an issue.  However, in more complex graphics programs it is often
  2019. desirable to write a program for a fixed screen resolution.  A common
  2020. practice is to develop graphics programs to run in modes 4 (for CGA), 9
  2021. (Tandy 1000 or PCjr), 12 (Hercules), 13 (EGA or VGA), and 19 or 20 (MCGA or
  2022. VGA).  The reason for selecting these five modes is they all use the same 320
  2023. by 200 resolution and will run on any IBM PC or PS/2 with graphics
  2024. capabilities.
  2025.  
  2026.      Example 3-8 performs the same function as example 3-7, but it uses the
  2027. fg_bestmode routine instead of fg_automode to restrict the program to 320 by
  2028. 200 graphics modes.  For this resolution, the fg_bestmode routine will first
  2029. check the availability of mode 19, followed by modes 13, 9, 4, and 12.  If
  2030. fg_bestmode determines no 320 by 200 graphics mode is available (indicated by
  2031. a return value of -1), the program prints an informational message and exits.
  2032. Otherwise it selects the video mode fg_bestmode proposes and continues.
  2033.  
  2034.                                  Example 3-8.
  2035.  
  2036.      #include <fastgraf.h>
  2037.      #include <stdio.h>
  2038.      #include <stdlib.h>
  2039.      void main(void);
  2040.  
  2041.                             Chapter 3:  Initializing the Video Environment  35
  2042.  
  2043.      void main()
  2044.      {
  2045.         int old_mode;
  2046.         int new_mode;
  2047.         char string[4];
  2048.  
  2049.         old_mode = fg_getmode();
  2050.         new_mode = fg_bestmode(320,200,1);
  2051.  
  2052.         if (new_mode < 0) {
  2053.            printf("This program requires a 320 by 200 graphics mode.\n");
  2054.            exit(1);
  2055.            }
  2056.  
  2057.         fg_setmode(new_mode);
  2058.  
  2059.         fg_setcolor(15);
  2060.         fg_text("I'm running in mode ",20);
  2061.         sprintf(string,"%d.",new_mode);
  2062.         fg_text(string,3);
  2063.         fg_waitkey();
  2064.  
  2065.         fg_setmode(old_mode);
  2066.         fg_reset();
  2067.      }
  2068.  
  2069.      If your program will not support all PC and PS/2 video modes with the
  2070. same resolution (for example, it will run in some but not all 320 by 200
  2071. graphics modes), you may want to consider using the fg_testmode routine
  2072. instead of fg_bestmode to check for available video modes.  You also may want
  2073. to use fg_testmode to change the video mode precedence used by fg_bestmode.
  2074. For example, mode 13 (EGA) is faster than mode 19 (MCGA), so you may want to
  2075. consider giving EGA precedence over MCGA, especially if your program does not
  2076. use more than 16 colors.
  2077.  
  2078.      Example 3-9 is similar to example 3-8, but it will only run in the 320
  2079. by 200 EGA, MCGA, and CGA graphics modes (video modes 13, 19, and 4
  2080. respectively).  The program uses fg_testmode to select its video mode.  Note
  2081. the order of calls to fg_testmode gives EGA precedence over MCGA, and MCGA
  2082. precedence over CGA.
  2083.  
  2084.                                  Example 3-9.
  2085.  
  2086.         #include <fastgraf.h>
  2087.         #include <stdio.h>
  2088.         #include <stdlib.h>
  2089.         void main(void);
  2090.  
  2091.         void main()
  2092.         {
  2093.            int old_mode;
  2094.            char string[4];
  2095.  
  2096.            old_mode = fg_getmode();
  2097.  
  2098.            if (fg_testmode(13,1))
  2099.  
  2100. 36  Fastgraph User's Guide
  2101.  
  2102.               fg_setmode(13);
  2103.            else if (fg_testmode(19,1))
  2104.               fg_setmode(19);
  2105.            else if (fg_testmode(4,1))
  2106.               fg_setmode(4);
  2107.            else {
  2108.               printf("This program requires an EGA, MCGA, or CGA.\n");
  2109.               exit(1);
  2110.               }
  2111.  
  2112.            fg_setcolor(15);
  2113.            fg_text("I'm running in mode ",20);
  2114.            sprintf(string,"%d.",getmode());
  2115.            fg_text(string,3);
  2116.            fg_waitkey();
  2117.  
  2118.            fg_setmode(old_mode);
  2119.            fg_reset();
  2120.         }
  2121.  
  2122.  
  2123.  
  2124. Summary of Video Initialization Routines
  2125.  
  2126.      This section summarizes the functional descriptions of the Fastgraph
  2127. routines presented in this chapter.  More detailed information about these
  2128. routines, including their arguments and return values, may be found in the
  2129. Fastgraph Reference Manual.
  2130.  
  2131.      FG_AUTOMODE determines the graphics video mode that offers the most
  2132. features for the user's display and adapter configuration.  The value it
  2133. returns helps determine a suitable value to pass to the fg_setmode routine.
  2134.  
  2135.      FG_BESTMODE is similar to fg_automode, but it excludes video modes that
  2136. do not offer the specified resolution and video page requirements.
  2137.  
  2138.      FG_CURSOR makes the text mode cursor visible or invisible.  This routine
  2139. has no effect when used in a graphics mode.
  2140.  
  2141.      FG_EGACHECK returns information about the active EGA or VGA adapter and
  2142. display.  It is useful in checking if the adapter has enough memory to run an
  2143. EGA-specific program.
  2144.  
  2145.      FG_GETLINES returns the number of text rows per screen for the current
  2146. video mode.
  2147.  
  2148.      FG_GETMODE returns the current video mode.  It is typically one of the
  2149. first Fastgraph routines called in a program.  The value returned by
  2150. fg_getmode can be retained to restore the original video mode when a program
  2151. transfers control back to DOS.
  2152.  
  2153.      FG_RESET is generally the last Fastgraph routine called in a program.
  2154. It only functions in text video modes.  When the ANSI.SYS driver is not
  2155. loaded, fg_reset merely erases the screen.  When ANSI.SYS is loaded, fg_reset
  2156. also restores any previously set screen attributes.
  2157.                             Chapter 3:  Initializing the Video Environment  37
  2158.  
  2159.      FG_SETLINES extends an 80-column text mode to 25, 43, or 50 lines per
  2160. screen.  This routine is only meaningful when running in 80-column text modes
  2161. on EGA, VGA, or MCGA systems (in other cases it does nothing).
  2162.  
  2163.      FG_SETMODE establishes a video mode and initializes Fastgraph's internal
  2164. parameters for that video mode.  It must be called before any Fastgraph
  2165. routine that performs video output.  A program can call fg_setmode as many
  2166. times as needed to switch between different video modes.
  2167.  
  2168.      FG_TESTMODE determines whether or not a specified video mode (with a
  2169. given number of video pages) is available on the user's system.
  2170. 38  Fastgraph User's Guide
  2171.  
  2172.  
  2173. Chapter 4
  2174.  
  2175. Coordinate Systems
  2176. 40  Fastgraph User's Guide
  2177.  
  2178.  
  2179. Overview
  2180.  
  2181.      Fastgraph uses three coordinate systems to perform text and graphics
  2182. output.  These coordinate systems are character space, screen space, and
  2183. world space.  The world space coordinate system is not available with
  2184. Fastgraph/Light.
  2185.  
  2186.  
  2187. Character Space
  2188.  
  2189.      The coordinate system used for displaying characters is called character
  2190. space.  Fastgraph uses character space for displaying characters in both text
  2191. and graphics video modes.  It can be thought of as a grid of rows and
  2192. columns, with each cell in the grid holding one character.  Each cell is
  2193. identified by its unique (row,column) integer coordinates.  The rows and
  2194. columns are numbered starting at zero; the origin is always the upper left
  2195. corner of the screen.  For example, in the 80-column by 25-row text modes (2,
  2196. 3, and 7), the (row,column) coordinates of the screen corners are shown in
  2197. the following diagram.
  2198.  
  2199.                             (0,0)           (0,79)
  2200.  
  2201.  
  2202.                             (24,0)         (24,79)
  2203.  
  2204. The number of rows and columns depends on the video mode, as shown in the
  2205. following table.  For graphics modes, the table also includes the width and
  2206. height in pixels of a character cell.
  2207.  
  2208.  
  2209.                        Mode  No. of  No. of Char. Char.
  2210.                       Number Columns Rows   Width Height
  2211.  
  2212.                          0     40     25
  2213.                          1     40     25
  2214.                          2     80     25
  2215.                          3     80     25
  2216.                          4     40     25    8     8
  2217.                          5     40     25    8     8
  2218.                          6     80     25    8     8
  2219.                          7     80     25
  2220.                          9     40     25    8     8
  2221.                         11     80     25    9     14
  2222.                         12     40     25    8     8
  2223.                         13     40     25    8     8
  2224.                         14     80     25    8     8
  2225.                         15     80     25    8     14
  2226.                         16     80     25    8     14
  2227.                         17     80     30    8     16
  2228.                         18     80     30    8     16
  2229.                         19     40     25    8     8
  2230.                         20     40     25    8     8
  2231.                         21     40     50    8     8
  2232.                         22     40     30    8     8
  2233.                         23     40     60    8     8
  2234.  
  2235.                                             Chapter 4:  Coordinate Systems  41
  2236.  
  2237.  
  2238.      Fastgraph includes two routines, fg_getmaxx and fg_getmaxy, that
  2239. respectively return the maximum column and row numbers in text modes.
  2240. Example 4-1 demonstrates these two routines in a text mode.  The program uses
  2241. fg_getmaxx and fg_getmaxy to obtain the maximum column and row numbers in
  2242. mode 3.  It then displays these values (79 and 24).
  2243.  
  2244.                                  Example 4-1.
  2245.  
  2246.                     #include <fastgraf.h>
  2247.                     #include <stdio.h>
  2248.                     void main(void);
  2249.  
  2250.                     void main()
  2251.                     {
  2252.                        int max_col;
  2253.                        int max_row;
  2254.                        int mode;
  2255.  
  2256.                        mode = fg_getmode();
  2257.                        fg_setmode(3);
  2258.  
  2259.                        max_col = fg_getmaxx();
  2260.                        max_row = fg_getmaxy();
  2261.  
  2262.                        fg_setmode(mode);
  2263.                        fg_reset();
  2264.  
  2265.                        printf("Last col = %d\n",max_col);
  2266.                        printf("Last row = %d\n",max_row);
  2267.                     }
  2268.  
  2269.  
  2270.  
  2271. Screen Space
  2272.  
  2273.      Screen space is one of two available coordinate systems in graphics
  2274. modes.  It uses the physical device coordinates.  Screen space can be thought
  2275. of as a grid of rows and columns, with each unit in the grid holding one
  2276. pixel.  Each pixel is identified by its unique (x,y) integer coordinates.
  2277. The rows and columns are numbered starting at zero; the origin is always the
  2278. upper left corner of the screen.  For example, in the 320 by 200 graphics
  2279. modes, the (x,y) coordinates of the screen corners are shown in the following
  2280. diagram.
  2281.  
  2282.                             (0,0)          (319,0)
  2283.  
  2284.  
  2285.                             (0,199)      (319,199)
  2286.  
  2287.      The Fastgraph routines fg_getmaxx and fg_getmaxy return the maximum x
  2288. and y screen coordinates when used in graphics modes, as shown in example
  2289. 42  Fastgraph User's Guide
  2290.  
  2291. 4-2.  The program uses fg_getmaxx and fg_getmaxy to obtain the maximum x and
  2292. y coordinates in the standard CGA four-color graphics mode (mode 4).  It then
  2293. displays these values (319 and 199).
  2294.  
  2295.                                  Example 4-2.
  2296.  
  2297.                       #include <fastgraf.h>
  2298.                       #include <stdio.h>
  2299.                       void main(void);
  2300.  
  2301.                       void main()
  2302.                       {
  2303.                          int maxx;
  2304.                          int maxy;
  2305.                          int mode;
  2306.  
  2307.                          mode = fg_getmode();
  2308.                          fg_setmode(4);
  2309.  
  2310.                          maxx = fg_getmaxx();
  2311.                          maxy = fg_getmaxy();
  2312.  
  2313.                          fg_setmode(mode);
  2314.                          fg_reset();
  2315.                          printf("(%d,%d)\n",maxx,maxy);
  2316.                       }
  2317.  
  2318. World Space
  2319.  
  2320.      World space is the other available coordinate system in graphics modes.
  2321. It utilizes user-defined floating point coordinates.  Fastgraph translates
  2322. world space coordinates into physical device coordinates (screen space), and
  2323. because of this it is somewhat slower than using screen space.  World space
  2324. can be thought of as a standard cartesian plane extending from the lower left
  2325. corner of the screen.
  2326.  
  2327.      Any program that uses world space coordinates must first initialize
  2328. Fastgraph's internal world space parameters.  The Fastgraph routine fg_initw
  2329. is provided for this purpose.  The fg_initw routine has no arguments and must
  2330. be called before any other routine that uses world space coordinates.
  2331.  
  2332.      The next step in using world space is to use the Fastgraph routine
  2333. fg_setworld to define the world space coordinates of the screen edges.  The
  2334. fg_setworld routine has four floating-point arguments -- the minimum x
  2335. coordinate (left edge), the maximum x coordinate (right edge), the minimum y
  2336. coordinate (bottom edge), and the maximum y coordinate (top edge).  For
  2337. example, if you define the world space coordinates with the statement
  2338.  
  2339.                        fg_setworld(-10.0,10.0,0.0,2.5);
  2340.  
  2341. the (x,y) coordinates of the screen corners would be defined as shown in the
  2342. following diagram.
  2343.  
  2344.                             (-10.0,2.5) (10.0,2.5)
  2345.  
  2346.                             (-10.0,0.0) (10.0,0.0)
  2347.  
  2348.                                             Chapter 4:  Coordinate Systems  43
  2349.  
  2350.  
  2351. Fastgraph includes a routine fg_getworld that returns the world space
  2352. extremes as defined in the most recent call to fg_setworld.
  2353.  
  2354.      Example 4-3 uses fg_setworld and fg_getworld to illustrate an
  2355. interesting application of world space.  This program calls another routine
  2356. named redraw (not shown) that erases the screen and draws a certain image
  2357. using world space coordinates.  The program draws the image, waits for a
  2358. keystroke, reduces the world space by a factor of two in each direction, and
  2359. then draws the image again.  This produces a zoom effect in which the image
  2360. appears twice as large as it was originally.
  2361.  
  2362.                                  Example 4-3.
  2363.  
  2364.               #include <fastgraf.h>
  2365.               #include <stdio.h>
  2366.               #include <stdlib.h>
  2367.               void main(void);
  2368.               void redraw(void);
  2369.  
  2370.               void main()
  2371.               {
  2372.                  int new_mode, old_mode;
  2373.                  double xmin, xmax, ymin, ymax;
  2374.  
  2375.                  old_mode = fg_getmode();
  2376.                  new_mode = fg_automode();
  2377.  
  2378.                  if (new_mode == 0) {
  2379.                     printf("This program requires graphics.\n");
  2380.                     exit(1);
  2381.                     }
  2382.  
  2383.                  fg_setmode(new_mode);
  2384.                  fg_initw();
  2385.  
  2386.                  fg_setworld(0.0,40.0,0.0,30.0);
  2387.                  redraw();
  2388.                  fg_waitkey();
  2389.  
  2390.                  fg_getworld(&xmin,&xmax,&ymin,&ymax);
  2391.                  fg_setworld(0.0,xmax*0.5,0.0,ymax*0.5);
  2392.                  redraw();
  2393.                  fg_waitkey();
  2394.  
  2395.                  fg_setmode(old_mode);
  2396.                  fg_reset();
  2397.               }
  2398.  
  2399. 44  Fastgraph User's Guide
  2400.  
  2401.  
  2402. Conversion Routines
  2403.  
  2404.      It is often necessary to convert coordinates between character space,
  2405. screen space, and world space.  Fastgraph includes eight conversion routines,
  2406. four for x coordinates and four for y coordinates, to perform such
  2407. conversions.  These routines return the translated coordinate as their
  2408. function value.
  2409.  
  2410.      The fg_xalpha and fg_yalpha routines convert screen space coordinates to
  2411. character space.  The fg_xalpha routine converts a screen space x coordinate
  2412. to the character space column that contains the coordinate.  Similarly, the
  2413. fg_yalpha routine converts a screen space y coordinate to the character space
  2414. row that contains the coordinate.
  2415.  
  2416.      The fg_xconvert and fg_yconvert routines convert character space
  2417. coordinates to screen space.  The fg_xconvert routine converts a character
  2418. space column to the screen space coordinate of its leftmost pixel.
  2419. Similarly, the fg_yconvert routine converts a character space row to the
  2420. screen space coordinate of its top (lowest-numbered) pixel.
  2421.  
  2422.      The fg_xscreen and fg_yscreen routines convert world space coordinates
  2423. to screen space.  The fg_xscreen routine translates x coordinates, while the
  2424. fg_yscreen routine translates y coordinates.  Conversely, the fg_xworld and
  2425. fg_yworld routines convert screen space coordinates to world space.  The
  2426. fg_xworld routine translates x coordinates, while the fg_yworld routine
  2427. translates y coordinates.
  2428.  
  2429.  
  2430. Summary of Coordinate Routines
  2431.  
  2432.      This section summarizes the functional descriptions of the Fastgraph
  2433. routines presented in this chapter.  More detailed information about these
  2434. routines, including their arguments and return values, may be found in the
  2435. Fastgraph Reference Manual.
  2436.  
  2437.      FG_GETMAXX returns the maximum x coordinate in screen space when used in
  2438. a graphics mode.  It returns the maximum column number in character space
  2439. when used in a text mode.
  2440.  
  2441.      FG_GETMAXY returns the maximum y coordinate in screen space when used in
  2442. a graphics mode.  It returns the maximum row number in character space when
  2443. used in a text mode.
  2444.  
  2445.      FG_GETWORLD returns the current world space limits, as defined in the
  2446. most recent call to fg_setworld.
  2447.  
  2448.      FG_INITW initializes Fastgraph's internal parameters for world space.
  2449. This routine must be called once, before any other routine that uses world
  2450. coordinates.
  2451.  
  2452.      FG_SETWORLD defines the world space coordinates that correspond to the
  2453. physical edges of the screen.
  2454.  
  2455.      FG_XALPHA and FG_YALPHA convert screen space coordinates to character
  2456. space.
  2457.                                             Chapter 4:  Coordinate Systems  45
  2458.  
  2459.      FG_XCONVERT and FG_YCONVERT convert character space coordinates to
  2460. screen space.
  2461.  
  2462.      FG_XSCREEN and FG_YSCREEN convert world space coordinates to screen
  2463. space.
  2464.  
  2465.      FG_XWORLD and FG_YWORLD convert screen space coordinates to world space.
  2466. 46  Fastgraph User's Guide
  2467.  
  2468.  
  2469. Chapter 5
  2470.  
  2471. The Use of Color
  2472. 48  Fastgraph User's Guide
  2473.  
  2474.  
  2475. Overview
  2476.  
  2477.      The use of color is an important part of any text or graphics
  2478. application.  This chapter explains color as it applies to text and graphics
  2479. modes.  It also describes palettes and video DAC registers for the graphics
  2480. video modes that offer this functionality.  Finally, an explanation of
  2481. Fastgraph's virtual colors is provided.
  2482.  
  2483.  
  2484. Text Modes
  2485.  
  2486.      The term color is not really correct in text modes because each
  2487. character cell has an associated attribute that controls the character's
  2488. appearance in that cell.  The meaning of the attribute differs for color and
  2489. monochrome text modes.
  2490.  
  2491.  
  2492. Color Modes
  2493.  
  2494.      In color text modes (modes 0, 1, 2, and 3), the attribute determines a
  2495. character's foreground color (the color of the character itself), its
  2496. background color (the color of that part of the character cell not covered by
  2497. the character), and whether or not it blinks.  Sixteen foreground colors
  2498. (numbered 0 to 15) are available, but only eight background colors (numbered
  2499. 0 to 7) are available.  The colors assigned to these values are listed in the
  2500. following table.
  2501.  
  2502.  
  2503.                    number color     number color
  2504.  
  2505.                       0   black        8   gray
  2506.                       1   blue         9   light blue
  2507.                       2   green       10   light green
  2508.                       3   cyan        11   light cyan
  2509.                       4   red         12   light red
  2510.                       5   magenta     13   light magenta
  2511.                       6   brown       14   yellow
  2512.                       7   white       15   bright white
  2513.  
  2514.  
  2515. At first it may seem the numbers have been arbitrarily assigned to the
  2516. colors.  Upon further inspection, however, it becomes apparent this is not
  2517. the case.  Each color number is a four bit quantity of the form IRGB, with I
  2518. representing the intensity, R the red component, G the green component, and B
  2519. the blue component.  If the corresponding bit is 1, it means the intensity or
  2520. color component is set.  For example, normal red would be represented by the
  2521. IRGB bit pattern 0100, which is 4 decimal, the color number for red.
  2522.  
  2523.      The fg_setattr routine defines the current text attribute.  Once
  2524. fg_setattr is called, Fastgraph displays all subsequent text using that
  2525. attribute.  The first argument of fg_setattr defines the foreground color,
  2526. which must be an integer between 0 and 15.  Its second argument defines the
  2527.                                               Chapter 5:  The Use of Color  49
  2528.  
  2529. background color, which must be between 0 and 7.  Its third argument
  2530. determines if the foreground color blinks (1 means it blinks, 0 means it does
  2531. not).  For example, the statement
  2532.  
  2533.                              fg_setattr(14,1,0);
  2534.  
  2535. specifies subsequent text will be displayed with a yellow foreground (14) on
  2536. a blue background (1) and will not blink (0).
  2537.  
  2538.      Another Fastgraph routine, fg_setcolor, also can be used to define text
  2539. attributes.  The fg_setcolor routine packs the three values passed to
  2540. fg_setattr into a single argument, as shown below.
  2541.  
  2542.  
  2543.                             bits  attribute
  2544.  
  2545.                             0-3   foreground color
  2546.                             4-6   background color
  2547.                              7    blinking
  2548.  
  2549. For example, calling fg_setcolor with an argument of 30 (1E hex) is
  2550. equivalent to calling fg_setattr with arguments of 14, 1, and 0.
  2551.  
  2552.      The Fastgraph routine fg_getcolor returns the current text attribute, as
  2553. defined in the most recent call to fg_setattr or fg_setcolor.  The
  2554. fg_getcolor routine has no arguments and returns the attribute as its
  2555. function value.  The returned value is encoded using the same scheme for
  2556. passing a text attribute to the fg_setcolor routine.
  2557.  
  2558.  
  2559. Monochrome Mode
  2560.  
  2561.      In the monochrome text mode (mode 7), colors are obviously not
  2562. available.  The attribute instead determines whether a character is
  2563. invisible, normal, bold, reversed, or certain combinations of these.  The
  2564. following table shows the values assigned to the available display
  2565. characteristics.
  2566.  
  2567.  
  2568.  
  2569.                  foreground  background  characteristic
  2570.  
  2571.                       0           0      invisible
  2572.                       0           7      reversed
  2573.                       1           0      underlined
  2574.                       7           0      normal
  2575.                       9           0      underlined bold
  2576.                      15           0      bold
  2577.  
  2578. Additionally, you can turn blinking on or off for each of these combinations.
  2579. Any combination of foreground and background values not listed in the above
  2580. table produces a normal display characteristic.
  2581. 50  Fastgraph User's Guide
  2582.  
  2583.      As in the color modes, the Fastgraph routines fg_setattr and fg_setcolor
  2584. define the current text attribute.  For example, the statement
  2585.  
  2586.                               fg_setattr(0,7,1);
  2587.  
  2588. specifies subsequent text will be displayed in reverse video (0,7) and will
  2589. blink (1).  The same attribute could be defined by calling fg_setcolor with
  2590. an argument of 240 (F0 hex).  The fg_getcolor routine is also available and
  2591. works as it does in the color text modes.
  2592.  
  2593.  
  2594. Graphics Modes
  2595.  
  2596.      In graphics modes, each pixel has an associated color value that
  2597. determines the color in which the pixel is displayed.  The number of
  2598. available colors depends on the video mode.  Some of the graphics modes also
  2599. have palette registers or video DAC registers to provide additional color
  2600. capabilities.  The example programs presented in this section show the use of
  2601. color in specific graphics video modes.
  2602.  
  2603.      The following subsections will discuss the use of color in each graphics
  2604. video mode.  In these discussions, there will be several references to a
  2605. group of colors called the standard color set.  This is a set of 16 colors
  2606. common to many of the graphics video modes (and to the color text modes).
  2607. The colors in the standard color set are listed in the following table.
  2608.  
  2609.  
  2610.                    number color     number color
  2611.  
  2612.                       0   black        8   gray
  2613.                       1   blue         9   light blue
  2614.                       2   green       10   light green
  2615.                       3   cyan        11   light cyan
  2616.                       4   red         12   light red
  2617.                       5   magenta     13   light magenta
  2618.                       6   brown       14   yellow
  2619.                       7   white       15   bright white
  2620.  
  2621.  
  2622.      At this point it is important to understand the difference between the
  2623. terms color number and color value.  Color number refers to the number that
  2624. defines a color in the standard color set (for example, green is color number
  2625. 2).  Color value refers to the actual value of a pixel in video memory, which
  2626. ultimately determines the color in which that pixel is displayed.  The color
  2627. value is sometimes just called the color.
  2628.  
  2629.      In each graphics mode, video memory is zeroed when the fg_setmode
  2630. routine is called.  This means all pixels are initially set to color value 0,
  2631. which by default is black.  For this reason, color value 0 is often called
  2632. the background color in graphics video modes.
  2633.  
  2634.      The Fastgraph routine fg_setcolor defines the color in which subsequent
  2635. graphics operations are performed.  This color is called the current color.
  2636.                                               Chapter 5:  The Use of Color  51
  2637.  
  2638. Depending on the video mode, the current color can reference a color value
  2639. (in CGA and Hercules graphics modes), a palette register (in Tandy, EGA, and
  2640. VGA graphics modes), or a video DAC register (in 256-color modes).  The
  2641. fg_setcolor routine takes a single integer argument that specifies the color.
  2642. When fg_setmode is called, it sets the current color to 0.  The Fastgraph
  2643. routine fg_getcolor returns the current color, as defined in the most recent
  2644. call to fg_setcolor.  The fg_getcolor routine has no arguments and returns
  2645. the current color as its function value.
  2646.  
  2647.  
  2648. CGA Color Modes
  2649.  
  2650.      The CGA color modes (modes 4 and 5) have six sets of available colors,
  2651. called palettes, numbered 0 to 5.  Each palette consists of four colors,
  2652. numbered 0 to 3.  In each palette, the background color (color value 0) can
  2653. be selected from the standard color set, but the other 3 colors are fixed.
  2654. The following table shows the fixed colors assigned to each palette.
  2655.  
  2656.  
  2657.                      palette 0       palette 1       palette 2
  2658.  
  2659.            color 1   light green     light cyan      light cyan
  2660.            color 2   light red       light magenta   light red
  2661.            color 3   yellow          bright white    bright white
  2662.  
  2663.                      palette 3       palette 4       palette 5
  2664.  
  2665.            color 1   green           cyan            cyan
  2666.            color 2   red             magenta         red
  2667.            color 3   brown           white           white
  2668.  
  2669.  
  2670. Palette 1, with a black background, is the default palette when you select
  2671. mode 4.  Palette 2, with a black background, is the default palette when you
  2672. select mode 5.
  2673.  
  2674.      The CGA color modes have a border area called the overscan between the
  2675. addressable pixel space and the physical edges of the screen.  The overscan
  2676. area is always displayed in the background color, regardless of which CGA
  2677. palette is used.
  2678.  
  2679.      In CGA color modes, the fg_setcolor routine defines the current color by
  2680. referencing one of the four color values.  The fg_palette routine selects one
  2681. of the six palettes and defines the background color for that palette.  The
  2682. first argument of the fg_palette routine is an integer between 0 and 5 that
  2683. specifies the palette number.  The second argument is an integer between 0
  2684. and 15 that defines the background color, using the color numbers in the
  2685. standard color set.
  2686.  
  2687.      Example 5-1 demonstrates the use of the fg_palette and fg_setcolor
  2688. routines in mode 4.  After establishing the video mode, the program selects
  2689. palette 0 and makes the background color blue (color number 1).  It then
  2690. makes color 3 in palette 0 (yellow) the current color and displays the word
  2691. "Hello".  Finally, it restores the original video mode and screen attributes
  2692. before returning to DOS.
  2693. 52  Fastgraph User's Guide
  2694.  
  2695.                                  Example 5-1.
  2696.  
  2697.                            #include <fastgraf.h>
  2698.                            void main(void);
  2699.  
  2700.                            void main()
  2701.                            {
  2702.                               int mode;
  2703.  
  2704.                               mode = fg_getmode();
  2705.                               fg_setmode(4);
  2706.  
  2707.                               fg_palette(0,1);
  2708.                               fg_setcolor(3);
  2709.                               fg_text("Hello",5);
  2710.                               fg_waitkey();
  2711.  
  2712.                               fg_setmode(mode);
  2713.                               fg_reset();
  2714.                            }
  2715.  
  2716. CGA Two-Color Mode
  2717.  
  2718.      The CGA two-color mode (mode 6) has a fixed background color (color
  2719. value 0) and a user-definable foreground color (color value 1).  The
  2720. background color is always black.  The foreground color is bright white by
  2721. default, but it can be changed to any of the colors in the standard color
  2722. set.  It should be mentioned that changing the foreground color works on true
  2723. CGA adapters, but there are very few EGA and VGA adapters that correctly
  2724. implement changing the foreground color in their mode 6 emulation.
  2725.  
  2726.      In mode 6, the fg_setcolor routine defines the current color by
  2727. referencing one of the two color values.  The fg_palette routine defines the
  2728. actual foreground color (that is, the color of pixels whose color value is
  2729. 1).  To be consistent with the other graphics modes, the fg_palette routine
  2730. has two arguments, but the first one is not used.  The second argument is an
  2731. integer between 0 and 15 that defines the foreground color, using the color
  2732. numbers in the standard color set.
  2733.  
  2734.      Example 5-2 demonstrates the use of the fg_palette and fg_setcolor
  2735. routines in mode 6.  After establishing the video mode, the program makes the
  2736. foreground color yellow (color number 14).  It then makes color 1 the current
  2737. color and displays the word "Hello".  Finally, it restores the original video
  2738. mode and screen attributes before returning to DOS.
  2739.  
  2740.                                  Example 5-2.
  2741.  
  2742.                            #include <fastgraf.h>
  2743.                            void main(void);
  2744.  
  2745.                            void main()
  2746.                            {
  2747.                               int mode;
  2748.  
  2749.                               mode = fg_getmode();
  2750.                               fg_setmode(6);
  2751.  
  2752.                                               Chapter 5:  The Use of Color  53
  2753.  
  2754.                               fg_palette(0,14);
  2755.                               fg_setcolor(1);
  2756.                               fg_text("Hello",5);
  2757.                               fg_waitkey();
  2758.  
  2759.                               fg_setmode(mode);
  2760.                               fg_reset();
  2761.                            }
  2762.  
  2763. Tandy and PCjr Modes
  2764.  
  2765.      The supported Tandy 1000 or PCjr graphics mode (mode 9) has 16 color
  2766. values, numbered 0 to 15.  Each color value references one of 16 user-
  2767. definable palette registers, often simply called palettes, also numbered 0 to
  2768. 15.  The values assigned to the palette registers determine the colors in
  2769. which pixels are displayed.  For example, if you assign palette register 2
  2770. the value for red, then pixels whose color value is 2 will be red.
  2771.  
  2772.      Each palette can assume one of the 16 colors in the standard color set.
  2773. By default, the values assigned to the 16 palettes correspond to the
  2774. identically numbered colors in the standard color set.  In other words,
  2775. palette 0 is assigned the value for black, palette 1 is assigned the value
  2776. for blue, and so forth.
  2777.  
  2778.      In mode 9, the fg_setcolor routine defines the current color by
  2779. referencing one of the 16 palette registers.  The fg_palette routine defines
  2780. the actual color assigned to a specific palette register.  The first argument
  2781. of the fg_palette routine is an integer between 0 and 15 that specifies the
  2782. palette number.  The second argument is an integer between 0 and 15 that
  2783. defines the palette value (the color assigned to the palette), using the IRGB
  2784. color numbers in the standard color set.
  2785.  
  2786.      You also can use the Fastgraph routine fg_setrgb to define the color
  2787. assigned to a specific palette register.  Whereas the fg_palette routine does
  2788. this using a color number from the standard color set, fg_setrgb defines a
  2789. palette register using red, green, and blue color components plus an
  2790. intensity component.  The first argument of the fg_setrgb routine is an
  2791. integer between 0 and 15 that specifies the palette register number.  The
  2792. remaining three arguments are each integer values between -1 and 1 that
  2793. respectively specify the red, green, and blue color components for that
  2794. palette register.  The meanings of the color components are:
  2795.  
  2796.      -1 = color bit and intensity bit are set
  2797.       0 = color bit is reset
  2798.       1 = color bit is set
  2799.  
  2800. Since there is only one intensity bit in mode 9 color values, specifying -1
  2801. for any of the RGB color components produces an intense color.  For example,
  2802. the color light cyan is color number 11 in the standard color set, and it is
  2803. produced by combining green and blue and setting the intensity bit.  This
  2804. means any of these four statements
  2805.  
  2806.                             fg_palette(1,11);
  2807.                             fg_setrgb(1,0,-1,1);
  2808.                             fg_setrgb(1,0,1,-1);
  2809.                             fg_setrgb(1,0,-1,-1);
  2810.  
  2811. 54  Fastgraph User's Guide
  2812.  
  2813.  
  2814. could be used to define palette register 1 as light cyan in mode 9.
  2815.  
  2816.      Example 5-3 demonstrates the use of the fg_palette and fg_setcolor
  2817. routines in mode 9.  After establishing the video mode, the program defines
  2818. palette 0 to be blue (1) and palette 1 to be yellow (14).  Note that defining
  2819. palette 0 changes the background color.  It then makes color 1 the current
  2820. color and displays the word "Hello".  After waiting for a keystroke, the
  2821. program changes the color of "Hello" by changing palette 1 to bright white
  2822. (15).  Finally, it restores the original video mode and screen attributes
  2823. before returning to DOS.
  2824.  
  2825.                                  Example 5-3.
  2826.  
  2827.                            #include <fastgraf.h>
  2828.                            void main(void);
  2829.  
  2830.                            void main()
  2831.                            {
  2832.                               int mode;
  2833.  
  2834.                               mode = fg_getmode();
  2835.                               fg_setmode(9);
  2836.  
  2837.                               fg_palette(0,1);
  2838.                               fg_palette(1,14);
  2839.  
  2840.                               fg_setcolor(1);
  2841.                               fg_text("Hello",5);
  2842.                               fg_waitkey();
  2843.  
  2844.                               fg_palette(1,15);
  2845.                               fg_waitkey();
  2846.  
  2847.                               fg_setmode(mode);
  2848.                               fg_reset();
  2849.                            }
  2850.  
  2851.  
  2852.  
  2853. Hercules Mode
  2854.  
  2855.      The Hercules graphics mode (mode 11) has a fixed background color (color
  2856. value 0) and a fixed foreground color (color value 1).  The background color
  2857. is always black, and the foreground color is dependent on the monochrome
  2858. display being used (typically, it is green, amber, or white).
  2859.  
  2860.      The fg_setcolor routine defines the current color value by referencing
  2861. one of the two color values.  The fg_palette routine has no effect in mode
  2862. 11.
  2863.  
  2864.      Example 5-4 demonstrates the use of the fg_setcolor routine in mode 11.
  2865. After establishing the video mode, the program makes color 1 the current
  2866. color and displays the word "Hello".  It then restores the original video
  2867. mode and screen attributes before returning to DOS.
  2868.                                               Chapter 5:  The Use of Color  55
  2869.  
  2870.                                  Example 5-4.
  2871.  
  2872.                            #include <fastgraf.h>
  2873.                            void main(void);
  2874.  
  2875.                            void main()
  2876.                            {
  2877.                               int mode;
  2878.  
  2879.                               mode = fg_getmode();
  2880.                               fg_setmode(11);
  2881.  
  2882.                               fg_setcolor(1);
  2883.                               fg_text("Hello",5);
  2884.                               fg_waitkey();
  2885.  
  2886.                               fg_setmode(mode);
  2887.                               fg_reset();
  2888.                            }
  2889.  
  2890.  
  2891. Hercules Low-Resolution Mode
  2892.  
  2893.      The Hercules low-resolution graphics mode (mode 12) has four color
  2894. values, numbered 0 to 3.  The background color is always black, colors 1 and
  2895. 2 are half intensity, and color 3 is full intensity.  Colors 1 and 2 both
  2896. produce normal intensity colors, but they do so with different pixel
  2897. patterns -- color 1 turns on the odd-numbered physical pixels, while color 2
  2898. turns on the even-numbered physical pixels.  The appearance of colors 1 to 3
  2899. is dependent on the monochrome display being used (typically, it is green,
  2900. amber, or white).
  2901.  
  2902.      The fg_setcolor routine defines the current color value by referencing
  2903. one of the four color values.  The fg_palette routine has no effect in mode
  2904. 12.
  2905.  
  2906.      Example 5-5 demonstrates the use of the fg_setcolor routine in mode 12.
  2907. After establishing the video mode, the program makes color 3 the current
  2908. color and displays the word "Hello".  It then restores the original video
  2909. mode and screen attributes before returning to DOS.
  2910.  
  2911.                                  Example 5-5.
  2912.  
  2913.                            #include <fastgraf.h>
  2914.                            void main(void);
  2915.  
  2916.                            void main()
  2917.                            {
  2918.                               int mode;
  2919.  
  2920.                               mode = fg_getmode();
  2921.                               fg_setmode(12);
  2922.  
  2923.                               fg_setcolor(3);
  2924.                               fg_text("Hello",5);
  2925.                               fg_waitkey();
  2926.  
  2927. 56  Fastgraph User's Guide
  2928.  
  2929.                               fg_setmode(mode);
  2930.                               fg_reset();
  2931.                            }
  2932.  
  2933.  
  2934.  
  2935. EGA 200-Line Modes
  2936.  
  2937.      The 200-line EGA graphics modes (modes 13 and 14) have 16 color values,
  2938. numbered 0 to 15.  Each color value references one of 16 user-definable
  2939. palette registers, often simply called palettes, also numbered 0 to 15.  The
  2940. values assigned to the palette registers determine the colors in which pixels
  2941. are displayed.  For example, if you assign palette register 2 the value for
  2942. red, then pixels whose color value is 2 will be red.
  2943.  
  2944.      Each palette can assume one of the 16 colors in the standard color set.
  2945. By default, the values assigned to the 16 palettes correspond to the
  2946. identically numbered colors in the standard color set.  In other words,
  2947. palette 0 is assigned the value for black, palette 1 is assigned the value
  2948. for blue, and so forth.
  2949.  
  2950.      In modes 13 and 14, the fg_setcolor routine defines the current color by
  2951. referencing one of 16 available palette registers.  The fg_palette routine
  2952. defines the actual color assigned to a specific palette register.  The first
  2953. argument of the fg_palette routine is an integer between 0 and 15 that
  2954. specifies the palette number.  The second argument is an integer that defines
  2955. the palette value (the color assigned to the palette).  Although the actual
  2956. colors are taken from the standard color set, the binary structure of a
  2957. palette value is different from the IRGB format used in the standard color
  2958. set.  In modes 13 and 14, the binary structure of a palette value is IxRGB;
  2959. bit 3 is ignored.  The mode 13 and mode 14 palette values that correspond to
  2960. the standard color set are thus:
  2961.  
  2962.  
  2963.                     value color      value color
  2964.  
  2965.                       0   black       16   gray
  2966.                       1   blue        17   light blue
  2967.                       2   green       18   light green
  2968.                       3   cyan        19   light cyan
  2969.                       4   red         20   light red
  2970.                       5   magenta     21   light magenta
  2971.                       6   brown       22   yellow
  2972.                       7   white       23   bright white
  2973.  
  2974.  
  2975.      You also can use the Fastgraph routine fg_setrgb to define the color
  2976. assigned to a specific palette register.  Whereas the fg_palette routine does
  2977. this using a color number from the standard color set, fg_setrgb defines a
  2978. palette register using red, green, and blue color components, plus an
  2979. intensity component.  The first argument of the fg_setrgb routine is an
  2980. integer between 0 and 15 that specifies the palette register number.  The
  2981. remaining three arguments are each integer values between -1 and 1 that
  2982.                                               Chapter 5:  The Use of Color  57
  2983.  
  2984. respectively specify the red, green, and blue color components for that
  2985. palette register.  The meanings of the color components are:
  2986.  
  2987.      -1 = color bit and intensity bit are set
  2988.       0 = color bit is reset
  2989.       1 = color bit is set
  2990.  
  2991. Since there is only one intensity bit in mode 13 and 14 color values,
  2992. specifying -1 for any of the RGB color components produces an intense color.
  2993. For example, the color light cyan is represented by the color value 19, and
  2994. it is produced by combining green and blue and setting the intensity bit.
  2995. This means any of these four statements
  2996.  
  2997.                             fg_palette(1,19);
  2998.                             fg_setrgb(1,0,-1,1);
  2999.                             fg_setrgb(1,0,1,-1);
  3000.                             fg_setrgb(1,0,-1,-1);
  3001.  
  3002. could be used to define palette register 1 as light cyan in modes 13 and 14.
  3003.  
  3004.      The Fastgraph routine fg_setcolor defines the color value (that is, the
  3005. palette number) in which subsequent graphics operations are performed.  The
  3006. fg_setcolor routine takes a single integer argument that specifies this
  3007. color.  When fg_setmode is called, it sets the color value to 0.  The
  3008. Fastgraph routine fg_getcolor returns the current color value, as defined in
  3009. the most recent call to fg_setcolor.  The fg_getcolor routine has no
  3010. arguments and returns the current color as the function value.
  3011.  
  3012.      Example 5-6 demonstrates the use of the fg_palette and fg_setcolor
  3013. routines in mode 13.  After establishing the video mode, the program defines
  3014. palette 0 to be blue (1) and palette 1 to be yellow (22).  Note that defining
  3015. palette 0 changes the background color.  It then makes color 1 the current
  3016. color and displays the word "Hello".  After waiting for a keystroke, the
  3017. program changes the color of "Hello" by changing palette 1 to bright white
  3018. (23).  Finally, it restores the original video mode and screen attributes
  3019. before returning to DOS.
  3020.  
  3021.                                  Example 5-6.
  3022.  
  3023.                            #include <fastgraf.h>
  3024.                            void main(void);
  3025.  
  3026.                            void main()
  3027.                            {
  3028.                               int mode;
  3029.  
  3030.                               mode = fg_getmode();
  3031.                               fg_setmode(13);
  3032.  
  3033.                               fg_palette(0,1);
  3034.                               fg_palette(1,22);
  3035.  
  3036.                               fg_setcolor(1);
  3037.                               fg_text("Hello",5);
  3038.                               fg_waitkey();
  3039.  
  3040. 58  Fastgraph User's Guide
  3041.  
  3042.                               fg_palette(1,23);
  3043.                               fg_waitkey();
  3044.  
  3045.                               fg_setmode(mode);
  3046.                               fg_reset();
  3047.                            }
  3048.  
  3049.  
  3050.  
  3051. EGA Monochrome Mode
  3052.  
  3053.      The EGA monochrome graphics mode (mode 15) assigns display attributes to
  3054. its four color values, numbered 0 to 3.  Each color value references one of
  3055. four user-definable palette registers, often simply called palettes, numbered
  3056. 0, 1, 4, and 5.  This numbering scheme might seem rather strange at first,
  3057. but it results from the disabling of two of the four video memory bit planes
  3058. in mode 15.  The values assigned to the palette registers determine the pixel
  3059. display attribute.  For example, if you assign palette register 1 the value
  3060. for bold, then pixels whose value is 1 will be bold.
  3061.  
  3062.      In mode 15, the fg_setcolor routine defines the current color (actually,
  3063. a display attribute) by referencing one of the four palette registers.  The
  3064. fg_palette routine defines the actual display attribute assigned to a
  3065. specific palette register.  The first argument of the fg_palette routine is
  3066. an integer that specifies the palette number.  The second argument is an
  3067. integer that defines the palette value (the display attribute assigned to the
  3068. palette).  For each palette register, the following table shows the default
  3069. palette value and its associated display attribute.
  3070.  
  3071.                          palette  palette  display
  3072.                          number   value    attribute
  3073.  
  3074.                             0        0     invisible
  3075.                             1        8     normal
  3076.                             4       24     bold
  3077.                             5       24     bold
  3078.  
  3079.      Example 5-7 demonstrates the use of the fg_palette and fg_setcolor
  3080. routines in mode 15.  After establishing the video mode, the program makes
  3081. color 4 (actually, palette 4, which is bold by default) the current color and
  3082. displays the word "Hello".  After waiting for a keystroke, the program
  3083. changes the display attribute of "Hello" by changing palette 4 to normal
  3084. intensity (palette value 8).  Finally, it restores the original video mode
  3085. and screen attributes before returning to DOS.
  3086.  
  3087.                                  Example 5-7.
  3088.  
  3089.                            #include <fastgraf.h>
  3090.                            void main(void);
  3091.  
  3092.                            void main()
  3093.                            {
  3094.                               int mode;
  3095.  
  3096.                                               Chapter 5:  The Use of Color  59
  3097.  
  3098.                               mode = fg_getmode();
  3099.                               fg_setmode(15);
  3100.  
  3101.                               fg_setcolor(4);
  3102.                               fg_text("Hello",5);
  3103.                               fg_waitkey();
  3104.  
  3105.                               fg_palette(4,8);
  3106.                               fg_waitkey();
  3107.  
  3108.                               fg_setmode(mode);
  3109.                               fg_reset();
  3110.                            }
  3111.  
  3112.  
  3113.  
  3114. EGA Enhanced Mode
  3115.  
  3116.      The EGA enhanced graphics mode (mode 16) has 16 color values, numbered 0
  3117. to 15.  Each color value references one of 16 user-definable palette
  3118. registers, often simply called palettes, also numbered 0 to 15.  The values
  3119. assigned to the palette registers determine the colors in which pixels are
  3120. displayed.  For example, if you assign palette register 2 the value for red,
  3121. then pixels whose color value is 2 will be red.
  3122.  
  3123.      Each palette can assume one of 64 available colors.  By default, the
  3124. values assigned to the 16 palettes correspond to the identically numbered
  3125. colors in the standard color set.  In other words, palette 0 is assigned the
  3126. value for black, palette 1 is assigned the value for blue, and so forth.
  3127. There are a few EGA-compatible adapters that do not properly assign the
  3128. default colors to the 16 palette registers, so it is a good practice to do
  3129. this explicitly in mode 16.
  3130.  
  3131.      In mode 16, the fg_setcolor routine defines the current color value by
  3132. referencing one of the 16 palette registers.  The fg_palette routine defines
  3133. the actual color assigned to a specific palette register.  The first argument
  3134. of the fg_palette routine is an integer between 0 and 15 that specifies the
  3135. palette number.  The second argument is an integer that defines the palette
  3136. value (the color assigned to the palette).  The binary structure of a palette
  3137. value is different from the IRGB format used in the standard color set.  In
  3138. mode 16, the binary structure of a palette value is a 6-bit quantity of the
  3139. form rgbRGB, where the lower case letters represent the low intensity (1/3
  3140. intensity) color components, and the upper case letters represent the normal
  3141. intensity (2/3 intensity) color components.  The mode 16 palette values that
  3142. correspond to the standard color set are:
  3143.  
  3144.                     value color      value color
  3145.  
  3146.                       0   black       56   gray
  3147.                       1   blue        57   light blue
  3148.                       2   green       58   light green
  3149.                       3   cyan        59   light cyan
  3150.                       4   red         60   light red
  3151.                       5   magenta     61   light magenta
  3152.                      20   brown       62   yellow
  3153.                       7   white       63   bright white
  3154.  
  3155. 60  Fastgraph User's Guide
  3156.  
  3157.  
  3158.      The normal intensity components in mode 16 produce the same normal
  3159. intensity colors as in other 16-color graphics modes.  Similarly, combining
  3160. the low and normal intensities in mode 16 produces the high intensity colors
  3161. of the other modes.  The only exception to this is for the default brown,
  3162. formed from the bit pattern 010100 (20 decimal).  This value produces a more
  3163. true brown than the value 6 decimal, which is really an olive green.
  3164.  
  3165.      The palette values used in mode 16 are 6-bit quantities, which means
  3166. there are 64 different colors available in mode 16.  This group of 64 colors
  3167. consists of the 16 colors in the standard color set plus 48 additional colors
  3168. that are not available in any of the other EGA modes.  However, because the
  3169. EGA palette registers hold 4-bit quantities, only 16 of these colors can be
  3170. displayed at the same time.  In other words, the EGA enhanced mode provides
  3171. the capability of displaying 16 simultaneous colors from a group of 64.
  3172.  
  3173.      You also can use the Fastgraph routine fg_setrgb to define the color
  3174. assigned to a specific palette register.  Whereas the fg_palette routine does
  3175. this using a value between 0 and 63, fg_setrgb defines a palette register
  3176. using red, green, and blue color components.  The first argument of the
  3177. fg_setrgb routine is an integer between 0 and 15 that specifies the palette
  3178. register number.  The remaining three arguments are each integer values
  3179. between 0 and 3 that respectively specify the intensities in thirds of the
  3180. red, green, and blue color components for that palette register.  For
  3181. example, the color cyan is represented by the value 3 in the above table, and
  3182. it is produced by combining normal intensity (2/3 intensity) green and blue.
  3183. This means either of the statements
  3184.  
  3185.                              fg_palette(1,3);
  3186.                              fg_setrgb(1,0,2,2);
  3187.  
  3188. could be used to define palette register 1 as cyan.
  3189.  
  3190.      Example 5-8 demonstrates the use of the fg_palette and fg_setcolor
  3191. routines in mode 16.  It uses the Fastgraph routine fg_rect (discussed in the
  3192. next chapter) to draw rectangles of a specified size.  After establishing the
  3193. video mode, the program uses a for loop to draw 16 equal-size rectangles, one
  3194. in each of the 16 color values.  In the same loop, the program uses the
  3195. fg_palette routine to change each palette to black.  The while loop that
  3196. follows performs four iterations.  The first iteration changes palette 0 to
  3197. 0, palette 1 to 1, and so forth.  Hence, the 16 rectangles appear in the
  3198. palette values 0 to 15.  The rectangles remain in these colors until is key
  3199. is pressed to begin the next iteration.  The second iteration changes palette
  3200. 0 to 16, palette 1 to 17, and so forth.  This makes the 16 rectangles appear
  3201. in the palette values 16 to 31.  Iterations three and four are similar, so
  3202. the overall effect of the program is to display all 64 colors, 16 at a time.
  3203. Finally, the program restores the original video mode and screen attributes
  3204. before returning to DOS.
  3205.                                               Chapter 5:  The Use of Color  61
  3206.  
  3207.                                  Example 5-8.
  3208.  
  3209.                 #include <fastgraf.h>
  3210.                 void main(void);
  3211.  
  3212.                 #define COLORS 16
  3213.                 #define WIDTH  40
  3214.  
  3215.                 void main()
  3216.                 {
  3217.                    int base;
  3218.                    int color;
  3219.                    int minx, maxx;
  3220.                    int mode;
  3221.  
  3222.                    mode = fg_getmode();
  3223.                    fg_setmode(16);
  3224.  
  3225.                    base = 0;
  3226.                    minx = 0;
  3227.                    maxx = WIDTH - 1;
  3228.  
  3229.                    for (color = 0; color < COLORS; color++) {
  3230.                       fg_palette(color,0);
  3231.                       fg_setcolor(color);
  3232.                       fg_rect(minx,maxx,0,349);
  3233.                       minx = maxx + 1;
  3234.                       maxx = maxx + WIDTH;
  3235.                       }
  3236.  
  3237.                    while (base < COLORS*4) {
  3238.                       for (color = 0; color < COLORS; color++)
  3239.                          fg_palette(color,base+color);
  3240.                       base += COLORS;
  3241.                       fg_waitkey();
  3242.                       }
  3243.  
  3244.                    fg_setmode(mode);
  3245.                    fg_reset();
  3246.                 }
  3247.  
  3248. VGA and MCGA Two-Color Mode
  3249.  
  3250.      The VGA and MCGA high-resolution two-color mode (mode 17) has a
  3251. background color (color value 0) and a foreground color (color value 1).
  3252. Each color value references one of two user-definable palette registers,
  3253. often simply called palettes, also numbered 0 and 1.  Each palette register
  3254. in turn references one of 16 user-definable 18-bit video DAC registers,
  3255. numbered 0 to 15.  The values assigned to the palette registers and video DAC
  3256. registers determine the colors in which pixels are displayed.  For example,
  3257. if palette register 1 contains the value 3, and video DAC register 3 contains
  3258. the color value for red, then pixels whose color value is 1 (that is, the
  3259. foreground pixels) will be red.
  3260.  
  3261.      By default, palette register 0 references video DAC register 0, and
  3262. palette register 1 references video DAC register 1.  In addition, video DAC
  3263. register 0 initially contains the color value for black, while the other 15
  3264. 62  Fastgraph User's Guide
  3265.  
  3266. video DAC registers (1 through 15) contain the color value for bright white.
  3267. This means background pixels (color value 0) are black by default, while
  3268. foreground pixels (color value 1) are bright white.
  3269.  
  3270.      The 18-bit video DAC values consist of three 6-bit red, green, and blue
  3271. color components.  Hence, each color component is an integer between 0 and
  3272. 63; increasing values produce more intense colors.  The default color
  3273. components for DAC register 0 are red=0, blue=0, and green=0, which produces
  3274. black.  The default values for the other DAC registers are red=63, blue=63,
  3275. and green=63, which produces bright white.  Because the video DAC registers
  3276. are 18 bits long, each DAC can specify one of 262,144 (218) colors.  However,
  3277. because the palette registers hold 1-bit quantities, only two of these colors
  3278. can be displayed at the same time.  In other words, mode 17 provides the
  3279. capability of displaying two simultaneous colors from a group of 262,144.
  3280.  
  3281.      In mode 17, the fg_setcolor routine defines the current color by
  3282. referencing one of the two palette registers.  The fg_palette routine defines
  3283. the value of a palette register by referencing one of the 16 video DAC
  3284. registers.  That is, the fg_palette routine specifies the video DAC register
  3285. that a palette register references.  The first argument of the fg_palette
  3286. routine is either 0 or 1 and specifies the palette number.  The second
  3287. argument is an integer between 0 and 15 that specifies the video DAC register
  3288. for that palette.
  3289.  
  3290.      The Fastgraph routine fg_setrgb defines the value of a video DAC
  3291. register in mode 17.  The first argument of the fg_setrgb routine is an
  3292. integer between 0 and 15 that specifies the DAC register number.  The
  3293. remaining three arguments are each integer values between 0 and 63 that
  3294. respectively specify the red, green, and blue color components for that DAC
  3295. register.
  3296.  
  3297.      Example 5-9 demonstrates the use of the fg_palette, fg_setrgb, and
  3298. fg_setcolor routines in mode 17.  After establishing the video mode, the
  3299. program defines DAC register 0 to be blue (red=0, green=0, blue=42) and DAC
  3300. register 1 to be yellow (red=63, green=63, blue=21).  Note that defining DAC
  3301. register 0 changes the background color because palette 0 references DAC
  3302. register 0.  The program then makes color 1 the current color (palette 1
  3303. still references DAC register 1) and displays the word "Hello" in yellow.
  3304. After waiting for a keystroke, the program changes the color of "Hello" by
  3305. making palette 1 reference DAC register 15 (which still contains its default
  3306. value, bright white).  Finally, it restores the original video mode and
  3307. screen attributes before returning to DOS.
  3308.  
  3309.                                  Example 5-9.
  3310.  
  3311.                           #include <fastgraf.h>
  3312.                           void main(void);
  3313.  
  3314.                           void main()
  3315.                           {
  3316.                              int mode;
  3317.  
  3318.                              mode = fg_getmode();
  3319.                              fg_setmode(17);
  3320.                              fg_setrgb(0,0,0,42);
  3321.                              fg_setrgb(1,63,63,21);
  3322.  
  3323.                                               Chapter 5:  The Use of Color  63
  3324.  
  3325.                              fg_setcolor(1);
  3326.                              fg_text("Hello",5);
  3327.                              fg_waitkey();
  3328.  
  3329.                              fg_palette(1,15);
  3330.                              fg_waitkey();
  3331.  
  3332.                              fg_setmode(mode);
  3333.                              fg_reset();
  3334.                           }
  3335.  
  3336.  
  3337.  
  3338. VGA 16-Color Mode
  3339.  
  3340.      The VGA high-resolution two-color mode (mode 18) has 16 color values,
  3341. numbered 0 to 15.  Each color value references one of 16 user-definable
  3342. palette registers, often simply called palettes, also numbered 0 to 15.  Each
  3343. palette register in turn references one of 16 user-definable 18-bit video DAC
  3344. registers, also numbered 0 to 15.  The values assigned to the palette
  3345. registers and video DAC registers determine the colors in which pixels are
  3346. displayed.  For example, if palette register 1 contains the value 3, and
  3347. video DAC register 3 contains the color value for red, then pixels whose
  3348. color value is 1 will be red.
  3349.  
  3350.      By default, each of the 16 palette registers references the video DAC
  3351. register of the same number.  In addition, the 16 video DAC registers
  3352. respectively contain the color values for the 16 colors in the standard color
  3353. set.
  3354.  
  3355.      The 18-bit video DAC values consist of three 6-bit red, green, and blue
  3356. color components.  Hence, each color component is an integer between 0 and
  3357. 63; increasing values produce more intense colors.  The default RGB color
  3358. components for the 16 video DAC registers are:
  3359.  
  3360.  
  3361.          DAC   R   G   B  color      DAC   R   G   B  color
  3362.  
  3363.           0    0   0   0  black       8   21  21  21  gray
  3364.           1    0   0  42  blue        9   21  21  63  light blue
  3365.           2    0  42   0  green      10   21  63  21  light green
  3366.           3    0  42  42  cyan       11   21  63  63  light cyan
  3367.           4   42   0   0  red        12   63  21  21  light red
  3368.           5   42   0  42  magenta    13   63  21  63  light magenta
  3369.           6   42  21   0  brown      14   63  63  21  yellow
  3370.           7   42  42  42  white      15   63  63  63  bright white
  3371.  
  3372.  
  3373. Because the video DAC registers are 18 bits long, each DAC can specify one of
  3374. 262,144 (218) colors.  However, because the palette registers hold 4-bit
  3375. quantities, only 16 of these colors can be displayed at the same time.  In
  3376. other words, mode 18 provides the capability of displaying 16 simultaneous
  3377. colors from a group of 262,144.
  3378. 64  Fastgraph User's Guide
  3379.  
  3380.  
  3381.      In mode 18, the fg_setcolor, fg_palette, and fg_setrgb routines function
  3382. exactly as in mode 17 with one exception:  there are 16 palette registers
  3383. instead of just two.  Example 5-9 on page 62 demonstrates the use of these
  3384. routines in mode 17, but it also would work in mode 18 if that video mode
  3385. number were specified in the call to fg_setmode.
  3386.  
  3387.  
  3388. VGA and MCGA 256-Color Modes
  3389.  
  3390.      The VGA and MCGA 256-color modes (modes 19 through 23) have 256 color
  3391. values, numbered 0 to 255.  Each color value directly references one of 256
  3392. user-definable 18-bit video DAC registers, also numbered 0 to 255.  The
  3393. values assigned to the video DAC registers determine the colors in which
  3394. pixels are displayed.  For example, if video DAC register 3 contains the
  3395. color value for red, then pixels whose color value is 3 will be red.
  3396.  
  3397.      By default, the first 16 video DAC registers (0 to 15) contain the color
  3398. values for the standard color set.  The next 16 DAC registers (16 to 31)
  3399. contain the color values for a gray scale of gradually increasing intensity.
  3400. The next 216 DAC registers (32 to 247) contain three groups of 72 colors
  3401. each, with the first group (32 to 103) at high intensity, the second group
  3402. (104 to 175) at moderate intensity, and the third group (176 to 247) at low
  3403. intensity.  Each group consists of three ranges of decreasing saturation
  3404. (increasing whiteness), with each range varying in hue from blue to red to
  3405. green.  Finally, the last 8 DAC registers (248 to 255) alternate between
  3406. black and bright white.  This information is summarized in the following
  3407. table.
  3408.  
  3409.           DACs        default color values
  3410.  
  3411.           0 to 15     standard color set
  3412.           16 to 31    gray scale of gradually increasing intensity
  3413.           32 to 55    high saturation, high intensity colors
  3414.           56 to 79    moderate saturation, high intensity colors
  3415.           80 to 103   low saturation, high intensity colors
  3416.           104 to 127  high saturation, moderate intensity colors
  3417.           128 to 151  moderate saturation, moderate intensity colors
  3418.           152 to 175  low saturation, moderateintensity colors
  3419.           176 to 199  high saturation, low intensity colors
  3420.           200 to 223  moderate saturation, low intensity colors
  3421.           224 to 247  low saturation, low intensity colors
  3422.           248 to 255  alternate between black and bright white
  3423.  
  3424.                                               Chapter 5:  The Use of Color  65
  3425.  
  3426.      The 18-bit video DAC values consist of three 6-bit red, green, and blue
  3427. color components.  Hence, each color component is an integer between 0 and
  3428. 63; increasing values produce more intense colors.  Because the video DAC
  3429. registers are 18 bits long, each DAC can specify one of 262,144 (218) colors.
  3430. However, because the color values are 8-bit quantities, only 256 of these
  3431. colors can be displayed at the same time.  In other words, modes 19 through
  3432. 23 provide the capability of displaying 256 simultaneous colors from a group
  3433. of 262,144.
  3434.  
  3435.      In the VGA and MCGA 256-color video modes, the fg_setcolor routine
  3436. defines the current color by referencing on of the 256 video DAC registers.
  3437. The fg_setrgb routine defines the actual color of a video DAC register.  The
  3438. first argument of the fg_setrgb routine is an integer between 0 and 255 that
  3439. specifies the DAC register number.  The remaining three arguments are each
  3440. integer values between 0 and 63 that respectively specify the red, green, and
  3441. blue color components for that DAC register.  Another Fastgraph routine,
  3442. fg_getrgb, returns the color components for a specified DAC register.  Its
  3443. arguments are the same as for fg_setrgb, except the last three arguments (the
  3444. return values) are passed by reference rather than by value.
  3445.  
  3446.      You also can use the Fastgraph routine fg_palette to define the value of
  3447. a video DAC register in modes 19 through 23.  The first argument of the
  3448. fg_palette routine is an integer between 0 and 255 that specifies the DAC
  3449. register number.  The second argument is an integer between 0 and 63 that
  3450. specifies the color value for that video DAC register, using the same 64
  3451. values as in the EGA enhanced mode (mode 16).
  3452.  
  3453.      Example 5-10 demonstrates the use of the fg_setcolor routine in mode 19.
  3454. The program uses the Fastgraph routine fg_rect to draw vertical lines.  After
  3455. establishing the video mode, the program uses a for loop to draw 256 vertical
  3456. lines, one in each of the 256 colors (using the default DAC values).
  3457. Finally, the program restores the original video mode and screen attributes
  3458. before returning to DOS.
  3459.  
  3460.    Example 5-10.                                Example 5-11.
  3461.  
  3462. #include<fastgraf.h>                    #include <fastgraf.h>
  3463. void main(void);                        void main(void);
  3464.  
  3465. #define COLORS 256                      void main()
  3466.                                         {
  3467. void main()                                int old_mode;
  3468. {                                          int red,green, blue;
  3469.    int base;
  3470.    int color;                              old_mode = fg_getmode();
  3471.    int mode;                               fg_setmode(19);
  3472.  
  3473. 66  Fastgraph User's Guide
  3474.  
  3475.   int x;
  3476.                                            fg_setcolor(103);
  3477.   mode = fg_getmode();                     fg_text("Hello",5);
  3478.   fg_setmode(19);                          fg_waitfor(18);
  3479.  
  3480.   x = 32;                                  fg_getrgb(103,&red,&green,&blue);
  3481.  
  3482.   for (color=0; color<COLORS; color++) {   while(red+green+blue > 0){
  3483.      fg_setcolor(color);                      if (red > 0) red--;
  3484.      fg_rect(x,x,0,199);                      if (green > 0) green--;
  3485.      x++;                                     if (blue > 0) blue--;
  3486.      }                                        fg_setrgb(103,red,green,blue);
  3487.   fg_waitkey();                               fg_waitfor(1);
  3488.                                               }
  3489.   fg_setmode(mode);
  3490.   fg_reset();                              fg_setmode(old_mode);
  3491. }                                          fg_reset();
  3492.                                           }
  3493.  
  3494.  
  3495.      Example 5-11 shows an interesting effect available in VGA and MCGA
  3496. modes.  The program uses the Fastgraph routine fg_waitfor (discussed in
  3497. Chapter 14) to delay the program's execution.  After establishing the video
  3498. mode, the program displays the word "Hello" in color 103, which by default is
  3499. a pastel blue.  It then uses the Fastgraph routine fg_getrgb to retrieve the
  3500. color components for this color.  The while loop gradually decreases the
  3501. color components until all three components are zero, which makes the word
  3502. "Hello" smoothly fade to black.  Finally, the program restores the original
  3503. video mode and screen attributes before returning to DOS.
  3504.  
  3505.      The fg_setrgb and fg_getrgb routines work with individual DAC registers.
  3506. If you want to define or retrieve a block of consecutive DAC registers, using
  3507. the fg_setdacs and fg_getdacs routines is more efficient.  The fg_setdacs
  3508. routine defines the values of a block of contiguous DAC registers.  Its first
  3509. argument is the index of the first DAC register to define (between 0 and
  3510. 255), and its second argument is the number of DAC registers to define
  3511. (between 1 and 256).  The third argument is a byte array containing the RGB
  3512. color components for the DAC registers being defined.  The array's first
  3513. three bytes contain the red, green, and blue components for the first DAC,
  3514.                                               Chapter 5:  The Use of Color  67
  3515.  
  3516. the next three for the second DAC, and so forth.  The size of this array must
  3517. be at least three times the value of the second argument.  The fg_getdacs
  3518. arguments are the same as those for fg_setdacs, but the RGB array instead
  3519. receives the current values of the specified DAC registers.  Both routines
  3520. treat the DAC register numbers in a circular fashion (for example, defining
  3521. four DACs starting with number 254 will define DACs 254, 255, 0, and 1).
  3522.  
  3523.      Example 5-12 is similar to example 5-11, but it fades many colors
  3524. simultaneously.  The program displays seven asterisks, one each in colors 9
  3525. through 15.  It uses fg_getdacs to obtain the current settings of the
  3526. corresponding DAC registers; these values are stored in the array RGBvalues.
  3527. The while loop gradually fades the RGB components to zero, using fg_setdacs
  3528. to update their values, similar to the method of example 5-11.  This
  3529. illustrates an attractive way of turning an image into a blank screen.
  3530.  
  3531.                                 Example 5-12.
  3532.  
  3533.                        #include <fastgraf.h>
  3534.                        void main(void);
  3535.  
  3536.                        void main()
  3537.                        {
  3538.                           int decreasing;
  3539.                           int i;
  3540.                           int old_mode;
  3541.                           char RGBvalues[21];
  3542.  
  3543.                           old_mode = fg_getmode();
  3544.                           fg_setmode(19);
  3545.  
  3546.                           for (i = 9; i <= 15; i++) {
  3547.                              fg_setcolor(i);
  3548.                              fg_text("*",1);
  3549.                              }
  3550.  
  3551.                           fg_getdacs(9,7,RGBvalues);
  3552.                           fg_waitfor(18);
  3553.  
  3554.                           do {
  3555.                              decreasing = 0;
  3556.                              for (i = 0; i < 21; i++)
  3557.                                 if (RGBvalues[i] > 0) {
  3558.                                    RGBvalues[i]--;
  3559.                                    decreasing = 1;
  3560.                                    }
  3561.                              fg_setdacs(9,7,RGBvalues);
  3562.                              fg_waitfor(1);
  3563.                              }
  3564.                           while (decreasing);
  3565.  
  3566.                           fg_setmode(old_mode);
  3567.                           fg_reset();
  3568.                        }
  3569.  
  3570.  
  3571. Note that examples 5-11 and 5-12 also would work in video modes 17 and 18 as
  3572. long as you just use the first 16 video DAC registers.
  3573. 68  Fastgraph User's Guide
  3574.  
  3575.  
  3576. RGB Color Mapping
  3577.  
  3578.      If you're developing an application that runs in 256-color and 16-color
  3579. graphics modes, you've probably noticed the inherent differences in defining
  3580. color values.  In fact, the palette register values even use different
  3581. structures within the various 16-color modes.  The Fastgraph routine
  3582. fg_maprgb helps simplify these differences.  It maps three RGB color
  3583. components (each between 0 and 63) into a 16-color palette value suitable for
  3584. the current video mode.  Of course, the range of available colors is much
  3585. more restricted in the 16-color modes than in the 256-color modes, so
  3586. fg_maprgb must map the RGB components into the closest available color.
  3587.  
  3588.      Example 5-13 runs in any 16-color or 256-color graphics mode and
  3589. demonstrates the use of the fg_maprgb routine.  In 256-color modes, the
  3590. program simply uses fg_setrgb to define DAC register 1 to a pastel blue
  3591. (red=45, green=49, blue=63).  In 16-color modes, however, the program calls
  3592. fg_maprgb to convert the color components into a palette value in IRGB,
  3593. IxRGB, or rgbRGB format (depending on the current video mode).  The fg_maprgb
  3594. return value is passed to fg_palette to set palette register 1 to the closest
  3595. available color defined by the specified RGB components.
  3596.  
  3597.                                 Example 5-13.
  3598.  
  3599.           #include <fastgraf.h>
  3600.           #include <stdio.h>
  3601.           #include <stdlib.h>
  3602.           void main(void);
  3603.  
  3604.           void main()
  3605.           {
  3606.              int new_mode, old_mode;
  3607.  
  3608.              new_mode = fg_bestmode(320,200,1);
  3609.              if (new_mode < 0 || new_mode == 4 || new_mode == 12) {
  3610.                 printf("This program requires a 320 x 200 ");
  3611.                 printf("16-color or 256-color graphics mode.\n");
  3612.                 exit(1);
  3613.                 }
  3614.              old_mode = fg_getmode();
  3615.              fg_setmode(new_mode);
  3616.  
  3617.              fg_setcolor(1);
  3618.              if (new_mode <= 16)
  3619.                 fg_palette(1,fg_maprgb(45,49,63));
  3620.              else
  3621.                 fg_setrgb(1,45,49,63);
  3622.              fg_text("Hello",5);
  3623.              fg_waitkey();
  3624.  
  3625.              fg_setmode(old_mode);
  3626.              fg_reset();
  3627.           }
  3628.  
  3629.                                               Chapter 5:  The Use of Color  69
  3630.  
  3631.  
  3632. Defining All Palette Registers
  3633.  
  3634.      Fastgraph includes a routine fg_palettes that defines all 16 palette
  3635. registers in modes 9, 13, 14, 16, and 18.  You also can use the fg_palettes
  3636. routine to define the first 16 video DAC registers in modes 19 through 23.
  3637. It has no effect in other video modes.
  3638.  
  3639.      Using fg_palettes is much faster than calling the fg_palette routine 16
  3640. times.  The argument to the fg_palettes routine is a 16-element integer array
  3641. that contains the color values assigned respectively to palette registers (or
  3642. video DAC registers) 0 to 15.  Example 5-14 demonstrates how to zero the
  3643. palette registers (that is, change them all to black) in mode 13.
  3644.  
  3645.                                 Example 5-14.
  3646.  
  3647.               #include <fastgraf.h>
  3648.               void main(void);
  3649.  
  3650.               int zeroes[] = {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0};
  3651.  
  3652.               void main()
  3653.               {
  3654.                  int mode;
  3655.  
  3656.                  mode = fg_getmode();
  3657.                  fg_setmode(13);
  3658.  
  3659.                  fg_palettes(zeroes);
  3660.  
  3661.                  fg_setmode(mode);
  3662.                  fg_reset();
  3663.               }
  3664.  
  3665. Of course, as this example is written, it appears to do nothing more than
  3666. blank the screen.  Its purpose is to show an example of the fg_palettes
  3667. routine.
  3668.  
  3669.  
  3670. Virtual Colors
  3671.  
  3672.      By this time it should be clear the use of color is rather specific to
  3673. each graphics video mode.  One of the most obvious differences is the number
  3674. of available colors in each mode; it ranges from 2 to 256.  By available
  3675. colors, we mean the number of colors that can be displayed simultaneously.
  3676.  
  3677.      To simplify programming in graphics modes, Fastgraph provides 256
  3678. virtual colors.  The virtual colors are used in the graphics video modes
  3679. having fewer than 256 available colors.  Virtual colors allow you to use 256
  3680. color indices in all graphics modes, even if a particular mode does not have
  3681. 256 available colors.
  3682.  
  3683.      When you establish a video mode with the fg_setmode routine, Fastgraph
  3684. initializes all the virtual color indices.  It does this by replicating the
  3685. video mode's color values through the 256 virtual color indices.  For
  3686. example, the CGA color modes (4 and 5) have four color values, numbered 0
  3687. through 3.  In these modes, the fg_setmode routine initializes color indices
  3688. 70  Fastgraph User's Guide
  3689.  
  3690. 0, 4, 8, ... , 252 to 0; color indices 1, 5, 9, ... , 253 to 1; color indices
  3691. 2, 6, 10, ... , 254 to 2; and color indices 3, 7, 11, ... , 255 to 3.
  3692. Similarly, in 16-color graphics modes the color indices 0, 16, 32, ... , 240
  3693. are set to 0, and so forth.  In the monochrome EGA graphics video mode (mode
  3694. 15), the color values are numbered 0, 1, 4, and 5, so fg_setmode replicates
  3695. the color indices in groups of eight, even though there are only four
  3696. available colors.  An analysis of the color value sequences reveals an often
  3697. useful feature:  by default, virtual color 0 is black and virtual color 15 is
  3698. white or bright white in all graphics video modes.
  3699.  
  3700.      It is thus possible to write a multiple-mode program using the same
  3701. color indices for each graphics mode.  For example, a program that contains
  3702. the statement fg_setcolor(5) would produce subsequent graphics in color 5
  3703. (magenta by default) when running in a 16-color graphics mode.  It would
  3704. produce subsequent graphics in color 1 (light cyan by default) when running
  3705. in a CGA color mode.  This is because 1 is the default value assigned to
  3706. virtual color index 5 in the CGA color modes.
  3707.  
  3708.      The fg_setmode routine establishes default values for the 256 virtual
  3709. color indices, but it might be desirable to assign other available colors to
  3710. them.  Going back to the discussion in the previous paragraph, color number 2
  3711. is light magenta in the default CGA mode 4 palette.  It might make more sense
  3712. if the color value 2 were assigned to virtual color index 5, as this would
  3713. make the graphics drawn in color 5 the same color in mode 4 as in other color
  3714. modes.  The Fastgraph routine fg_defcolor is provided for this purpose.
  3715.  
  3716.      The fg_defcolor routine assigns a color value to a virtual color index.
  3717. It has two arguments:  the first specifies the virtual color index (between 0
  3718. and 255), and the second specifies the color value (between 0 and the number
  3719. of available colors in the current video mode).  For example, the statement
  3720.  
  3721.                               fg_defcolor(5,2);
  3722.  
  3723. would assign the color value 2 to the color index 5.  Another Fastgraph
  3724. routine, fg_getindex, returns the current value assigned to a specified color
  3725. index.  After executing the above call to fg_defcolor, the statement
  3726.  
  3727.                            color = fg_getindex(5);
  3728.  
  3729. would store the value 2 (the current value of color index 5) in the integer
  3730. variable color.
  3731.  
  3732.      It is important to understand the difference between virtual colors and
  3733. palette registers.  Modifying the value of a palette register changes the
  3734. color of all pixels already drawn using that palette.  Modifying a virtual
  3735. color index does not do this; it only specifies any graphics drawn in that
  3736. color from this point on will appear in the new color.
  3737.  
  3738.      Example 5-15 demonstrates the use of virtual colors in mode 4.  After
  3739. establishing the video mode, the program uses the fg_defcolor routine to
  3740. define virtual color indices 0 and 255 to be 1, which by default is light
  3741. cyan in mode 4.  It then draws characters using color indices 0, 1, and 255,
  3742. and in each case the characters appear in light cyan.  Finally, the program
  3743. restores the original video mode and screen attributes before returning to
  3744. DOS.
  3745.                                               Chapter 5:  The Use of Color  71
  3746.  
  3747.                                 Example 5-15.
  3748.  
  3749.                            #include <fastgraf.h>
  3750.                            void main(void);
  3751.  
  3752.                            void main()
  3753.                            {
  3754.                               int mode;
  3755.  
  3756.                               mode = fg_getmode();
  3757.                               fg_setmode(4);
  3758.  
  3759.                               fg_defcolor(0,1);
  3760.                               fg_defcolor(255,1);
  3761.  
  3762.                               fg_setcolor(0);
  3763.                               fg_text("0",1);
  3764.                               fg_setcolor(1);
  3765.                               fg_text(" 1",2);
  3766.                               fg_setcolor(255);
  3767.                               fg_text(" 255",4);
  3768.                               fg_waitkey();
  3769.  
  3770.                               fg_setmode(mode);
  3771.                               fg_reset();
  3772.                            }
  3773.  
  3774.  
  3775. A Multiple-Mode Example
  3776.  
  3777.      Even though the color capabilities differ between the supported video
  3778. modes, Fastgraph makes it easy to write a program that runs in many video
  3779. modes.  This section will present an example of such a program.
  3780.  
  3781.      Example 5-16 illustrates a program that will run in any of Fastgraph's
  3782. supported video modes.  The program first asks for the video mode number,
  3783. checks if the mode number is valid, and then checks if the requested mode is
  3784. available on the user's system.  After doing this, the program establishes
  3785. the video mode and performs its mode-specific code.  It then displays a brief
  3786. message that includes the video mode number in which the program is running.
  3787. This information remains on the screen until a key is pressed, at which time
  3788. the program restores the original video mode and screen attributes before
  3789. returning to DOS.
  3790.  
  3791.                                 Example 5-16.
  3792.  
  3793.        #include <fastgraf.h>
  3794.        #include <stdio.h>
  3795.        #include <stdlib.h>
  3796.        void main(void);
  3797.  
  3798.        void main()
  3799.        {
  3800.           int mode, old_mode;
  3801.           char string[5];
  3802.  
  3803. 72  Fastgraph User's Guide
  3804.  
  3805.        /* Ask for the video mode number */
  3806.           printf("Which video mode? ");
  3807.           scanf("%d",&mode);
  3808.  
  3809.        /* Make sure the entered value is valid */
  3810.           if (mode < 0 || mode > 23) {
  3811.              printf("%d is not a valid video mode number.\n",mode);
  3812.              exit(1);
  3813.              }
  3814.  
  3815.        /* Make sure the requested video mode is available */
  3816.           if (fg_testmode(mode,1) == 0) {
  3817.              printf("Mode %d is not available on this system.\n",mode);
  3818.              exit(1);
  3819.              }
  3820.  
  3821.        /* Establish the video mode */
  3822.           old_mode = fg_getmode();
  3823.           fg_setmode(mode);
  3824.  
  3825.        /* Perform mode-specific initializations */
  3826.           if (mode <= 3 || mode == 7)   /* text modes */
  3827.              fg_cursor(0);
  3828.  
  3829.           else if (mode == 4 || mode == 5) { /* CGA color modes */
  3830.              fg_palette(0,0);
  3831.              fg_defcolor(14,3);
  3832.              }
  3833.  
  3834.           else if (mode == 6) {         /* CGA two-color mode */
  3835.              fg_palette(0,14);
  3836.              fg_defcolor(14,1);
  3837.              }
  3838.  
  3839.           else if (mode == 11)          /* Hercules mode */
  3840.              fg_defcolor(14,1);
  3841.  
  3842.           else if (mode == 12)          /* Hercules low-res mode */
  3843.              fg_defcolor(14,3);
  3844.  
  3845.           else if (mode == 17) {        /* VGA two-color mode */
  3846.              fg_palette(1,14);
  3847.              fg_setrgb(14,63,63,21);
  3848.              fg_defcolor(14,1);
  3849.              }
  3850.  
  3851.        /* Display a message that includes the video mode number */
  3852.           fg_setcolor(14);
  3853.           fg_text("I'm running in mode ",20);
  3854.           sprintf(string,"%d. ",mode);
  3855.           fg_text(string,3);
  3856.  
  3857.        /* Wait for a keystroke */
  3858.           fg_waitkey();
  3859.  
  3860.                                               Chapter 5:  The Use of Color  73
  3861.  
  3862.        /* Restore the original video mode and screen attributes */
  3863.           fg_setmode(old_mode);
  3864.           fg_reset();
  3865.        }
  3866.  
  3867.      Example 5-16 displays its message in yellow for those video modes that
  3868. offer color.  In monochrome video modes, it displays the message in normal
  3869. intensity.  The program uses virtual color 14, which by default is yellow in
  3870. many video modes; the mode-specific code in example 5-16 makes color 14 yellow
  3871. in other video modes.  In text video modes (modes 0 to 3 and 7), the program
  3872. uses the fg_cursor routine to make the cursor invisible.  In CGA color modes
  3873. (modes 4 and 5), the program uses the fg_palette routine to select a CGA
  3874. palette that contains yellow as color 3 and then uses fg_defcolor to assign
  3875. color 3 to virtual color 14.  In CGA two-color mode (mode 6), the program uses
  3876. the fg_palette routine to make color 1 yellow and then uses fg_defcolor to
  3877. assign color 1 to virtual color 14.  In the Hercules modes (modes 11 and 12),
  3878. the program uses the fg_defcolor routine to assign the value for normal
  3879. intensity pixels to color 14.  In VGA two-color mode (mode 17), the program
  3880. uses the fg_palette routine to assign video DAC register 14 to palette
  3881. register 1.  It then defines video DAC register 14 to be yellow with the
  3882. fg_setrgb routine and finally uses fg_defcolor to assign color 1 (that is,
  3883. palette register 1) to virtual color 14.  In all other video modes, color 14
  3884. is yellow by default.
  3885.  
  3886.  
  3887. Summary of Color-Related Routines
  3888.  
  3889.      This section summarizes the functional descriptions of the Fastgraph
  3890. routines presented in this chapter.  More detailed information about these
  3891. routines, including their arguments and return values, may be found in the
  3892. Fastgraph Reference Manual.
  3893.  
  3894.      FG_DEFCOLOR assigns a color value to a virtual color index.  This routine
  3895. is only meaningful in the graphics video modes that have fewer than 256
  3896. available colors.
  3897.  
  3898.      FG_GETCOLOR returns the current text attribute (in text modes) or color
  3899. index (in graphics modes), as specified in the most recent call to fg_setattr
  3900. or fg_setcolor.
  3901.  
  3902.      FG_GETDACS retrieves the red, green, and blue color components for a
  3903. block of consecutively numbered video DAC registers.  This routine is only
  3904. meaningful in VGA and MCGA graphics modes.
  3905.  
  3906.      FG_GETINDEX returns the color value assigned to a specified virtual
  3907. color index.  In text modes and in graphics modes that have 256 available
  3908. colors, this routine returns the value passed to it.
  3909.  
  3910.      FG_GETRGB returns the red, green, and blue color components for a
  3911. specified video DAC register.  This routine is only meaningful in VGA and
  3912. MCGA graphics modes.
  3913.  
  3914.       FG_MAPRGB maps six-bit red, green, and blue color components into a
  3915. suitable palette value for the current video mode.  You can then pass this
  3916. value to the fg_palette routine.  This routine is meaningful only in 16-color
  3917. graphics video modes.
  3918. 74  Fastgraph User's Guide
  3919.  
  3920.      FG_PALETTE has different functions depending on the current graphics
  3921. video mode.  For the CGA four-color modes, it establishes the current palette
  3922. (of six available) and defines the background color for that palette.  In the
  3923. CGA two-color mode, it defines the foreground color.  For the Tandy/PCjr,
  3924. EGA, and VGA graphics modes, it defines the value of a single palette
  3925. register.  For the 256-color MCGA and VGA graphics modes, it defines the
  3926. value of a single video DAC register.  The fg_palette routine has no effect
  3927. in text modes or Hercules graphics modes.
  3928.  
  3929.      FG_PALETTES defines all 16 palette registers (in Tandy/PCjr, EGA, and
  3930. VGA graphics modes), or the first 16 video DAC registers (in 256-color MCGA
  3931. and VGA graphics modes).  The fg_palettes routine has no effect in text
  3932. modes, CGA graphics modes, or Hercules graphics modes.
  3933.  
  3934.      FG_SETATTR establishes the current text attribute in text video modes.
  3935. This routine has no effect in graphics modes.
  3936.  
  3937.      FG_SETCOLOR establishes the current color index (which may be a virtual
  3938. color index in graphics modes).  In text modes, the fg_setcolor routine
  3939. provides an alternate method of establishing the current text attribute.
  3940.  
  3941.      FG_SETDACS defines the values of a block of consecutively numbered video
  3942. DAC registers by specifying their red, green, and blue color components.
  3943. This routine is only meaningful in VGA and MCGA graphics modes.
  3944.  
  3945.      FG_SETRGB defines the value of a single palette register (in Tandy/PCjr
  3946. and EGA graphics modes) or video DAC register (in VGA and MCGA modes) by
  3947. specifying its red, green, and blue color components.  The fg_setrgb routine
  3948. has no effect in text modes, CGA graphics modes, or Hercules graphics modes.
  3949.  
  3950.  
  3951. Chapter 6
  3952.  
  3953. Graphics Fundamentals
  3954. 76  Fastgraph User's Guide
  3955.  
  3956. Overview
  3957.  
  3958.      This chapter describes Fastgraph's fundamental graphics routines,
  3959. sometimes called graphics primitives.  These routines perform such functions
  3960. as clearing the screen, drawing points, drawing solid and dashed lines,
  3961. drawing closed shapes (polygons, circles, and ellipses), drawing rectangles
  3962. (solid and dithered), and filling arbitrary regions.  Most of these routines
  3963. have no effect in text video modes, but there are a few exceptions, and they
  3964. will be noted in the descriptions of those routines.
  3965.  
  3966.  
  3967. Clearing the Screen
  3968.  
  3969.      The Fastgraph routine fg_erase clears the entire screen in any video
  3970. mode.  In text modes, fg_erase clears the screen by storing a space character
  3971. (ASCII 32) with a gray foreground attribute in each character cell.  In
  3972. graphics modes, fg_erase clears the screen by setting each pixel to zero.
  3973. This of course causes each pixel to be displayed its background color.  The
  3974. fg_erase routine has no arguments.
  3975.  
  3976.  
  3977. Clipping
  3978.  
  3979.      The suppression of graphics outside a pre-defined area is called
  3980. clipping.  Many of Fastgraph's graphics-oriented routines provide clipping,
  3981. either automatically or through a special version of the routine.
  3982.  
  3983.      Fastgraph includes two routines, fg_setclip and fg_setclipw, to define a
  3984. rectangular clipping region.  The fg_setclip routine defines the clipping
  3985. region in screen space, while the fg_setclipw routine performs the same
  3986. function in world space.  Each routine takes four arguments:  the minimum x,
  3987. the maximum x, the minimum y, and the maximum y coordinate of the clipping
  3988. region.  The arguments are integer quantities for fg_setclip and floating
  3989. point quantities for fg_setclipw.  For example, the statement
  3990.  
  3991.                            fg_setclip(0,159,0,99);
  3992.  
  3993. would define the upper left quadrant of the screen as the clipping region in
  3994. a 320 by 200 graphics mode.
  3995.  
  3996.      An implicit clipping region equal to the entire screen is defined as
  3997. part of the fg_setmode routine's initializations.  Clipping is not supported
  3998. for text modes.
  3999.  
  4000.  
  4001. Points
  4002.  
  4003.      The Fastgraph routine fg_point provides the most basic graphics
  4004. operation -- setting a pixel to a specified color.  The fg_point routine has
  4005. two integer arguments.  The first specifies the pixel's x coordinate, and the
  4006. second its y coordinate.  The pixel is drawn using the current color value,
  4007. as specified in the most recent call to fg_setcolor.  There is also a world
  4008. space version of this routine, fg_pointw, that uses floating point arguments.
  4009.  
  4010.      Another Fastgraph routine is available for reading a pixel's color
  4011. value.  The fg_getpixel routine has two integer arguments that specify the
  4012. (x,y) coordinates for the pixel of interest.  There is no world space version
  4013.                                          Chapter 6:  Graphics Fundamentals  77
  4014.  
  4015. of the fg_getpixel routine, but you can obtain a pixel's color value in world
  4016. space by applying the fg_xscreen and fg_yscreen functions to the world space
  4017. coordinates and passing the resulting values to fg_getpixel.
  4018.  
  4019.      Example 6-1 uses the fg_point routine to draw 100 random points in
  4020. random colors.  It also uses the fg_getpixel routine to insure no two points
  4021. are adjacent.  The program establishes a graphics video mode with the
  4022. fg_automode and fg_setmode routines.  Next, it determines the maximum color
  4023. value for the selected video mode; note if we used virtual colors (color
  4024. indices above the maximum color value), some of the colors would be the
  4025. background color and would thus produce invisible points.  The main part of
  4026. the program is a while loop that first generates a random pair of (x,y)
  4027. screen coordinates.  It then calls the fg_getpixel routine to check the
  4028. pixels at (x,y) and the eight adjacent positions.  If none of these pixels
  4029. are set, the program generates a random color value and draws a point in that
  4030. color.  After doing this 100 times, the program waits for a keystroke,
  4031. restores the original video mode and screen attributes, and then returns to
  4032. DOS.
  4033.  
  4034.                                  Example 6-1.
  4035.  
  4036.  
  4037.   #include <fastgraf.h>
  4038.   #include <stdlib.h>
  4039.  
  4040.   void main(void);
  4041.   void main()
  4042.   {
  4043.      int area;
  4044.      int color, old_color;
  4045.      int left;
  4046.      int max_color, max_x, max_y;
  4047.      int new_mode, old_mode;
  4048.      int x, y;
  4049.  
  4050.      old_mode = fg_getmode();
  4051.      new_mode = fg_automode();
  4052.      fg_setmode(new_mode);
  4053.  
  4054. 78  Fastgraph User's Guide
  4055.  
  4056.      if (new_mode == 4)
  4057.         max_color = 3;
  4058.  
  4059.      else if (new_mode == 11 || new_mode == 17)
  4060.         max_color = 1;
  4061.  
  4062.      else if (new_mode == 19)
  4063.         max_color = 255;
  4064.  
  4065.      else
  4066.         max_color = 15;
  4067.  
  4068.      left = 100;
  4069.      max_x = fg_getmaxx() - 1;
  4070.      max_y = fg_getmaxy() - 1;
  4071.  
  4072.      while (left > 0) {
  4073.  
  4074.         x = rand() % max_x + 1;
  4075.         y = rand() % max_y + 1;
  4076.  
  4077.         area = fg_getpixel(x-1,y-1) + fg_getpixel(x,y-1) + fg_getpixel(x+1,y-1)
  4078.              + fg_getpixel(x-1,y)   + fg_getpixel(x,y)   + fg_getpixel(x+1,y)
  4079.              + fg_getpixel(x-1,y+1) + fg_getpixel(x,y+1) + fg_getpixel(x+1,y+1);
  4080.  
  4081.         if (area == 0) {
  4082.            color = rand() % max_color + 1;
  4083.            fg_setcolor(color);
  4084.            fg_point(x,y);
  4085.            left--;
  4086.            }
  4087.         }
  4088.  
  4089.      fg_waitkey();
  4090.  
  4091.      fg_setmode(old_mode);
  4092.      fg_reset();
  4093.   }
  4094.  
  4095.                                          Chapter 6:  Graphics Fundamentals  79
  4096.  
  4097. The Graphics Cursor
  4098.  
  4099.      Many of Fastgraph's graphics routines depend on the position of the
  4100. graphics cursor as a reference point.  For example, Fastgraph includes
  4101. routines to draw lines from the graphics cursor position to a specified
  4102. position, and the image display routines discussed in Chapter 9 display or
  4103. retrieve an image relative to the graphics cursor position.  The graphics
  4104. cursor is not a cursor in the true sense; it is simply a pair of (x,y)
  4105. coordinates with a special meaning.  The fg_setmode routine sets the graphics
  4106. cursor position to the screen space coordinates (0,0), and the fg_initw
  4107. routine sets it to the world space coordinates (0.0,0.0).
  4108.  
  4109.      Fastgraph includes four routines for changing the graphics cursor
  4110. position.  The fg_move routine sets it to an absolute screen space position,
  4111. while the fg_movew routine sets it to an absolute world space position.  The
  4112. fg_moverel routine sets the graphics cursor position to a screen space
  4113. position relative to its current position.  The fg_moverw routine does the
  4114. same in world space.
  4115.  
  4116.      Each of these routines has two arguments that specify the (x,y)
  4117. coordinates of the new position.  For the screen space routines, the
  4118. arguments are integer quantities.  For the world space routines, the
  4119. arguments are floating point quantities.
  4120.  
  4121.      You can obtain the screen space coordinates of the graphics cursor
  4122. position with the fg_getxpos and fg_getypos routines.  These routines have no
  4123. arguments and respectively return the x and y coordinates of the graphics
  4124. cursor position as the function value.  To obtain the world space coordinates
  4125. of the graphics cursor position, you can apply the fg_xworld and fg_yworld
  4126. functions to the return values of fg_getxpos and fg_getypos.
  4127.  
  4128.  
  4129. Solid Lines
  4130.  
  4131.      Fastgraph includes four routines for drawing solid lines.  All four
  4132. routines draw lines in the current color value (as determined by the most
  4133. recent call to fg_setcolor) and observe the clipping limits.  The fg_draw
  4134. routine draws a line from the current graphics cursor position to an absolute
  4135. screen space position, while the fg_draww routine draws a line to an absolute
  4136. world space position.  The fg_drawrel routine draws a line from the current
  4137. graphics cursor position to a screen space position relative to it.  The
  4138. fg_drawrw routine does the same in world space.
  4139. 80  Fastgraph User's Guide
  4140.  
  4141.      Each of these routines has two arguments that specify the (x,y)
  4142. coordinates of the destination position.  For the screen space routines, the
  4143. arguments are integer quantities.  For the world space routines, the
  4144. arguments are floating point quantities.  In either case the destination
  4145. position becomes the new graphics cursor position.  This makes it possible to
  4146. draw connected lines without calling a graphics cursor movement routine
  4147. between successive calls to a line drawing routine.
  4148.  
  4149.      Examples 6-2 and 6-3 each draw a pair of crossed lines that divide the
  4150. screen into quadrants.  Example 6-2 does this using the fg_move and fg_draw
  4151. routines, while example 6-3 uses the fg_moverel and fg_drawrel routines.
  4152. Both examples draw the lines in bright white, the default for color 15 in all
  4153. graphics video modes.
  4154.  
  4155.               Example 6-2.                          Example 6-3.
  4156.  
  4157.      #include <fastgraf.h>                 #include <fastgraf.h>
  4158.      void main(void);                      void main(void);
  4159.  
  4160.      void main()                           void main()
  4161.      {                                     {
  4162.         int max_x, max_y;                     int max_x, max_y;
  4163.         int mid_x, mid_y;                     int mid_x, mid_y;
  4164.         int new_mode, old_mode;               int new_mode, old_mode;
  4165.  
  4166.         old_mode = fg_getmode();              old_mode = fg_getmode();
  4167.         new_mode = fg_automode();             new_mode = fg_automode();
  4168.         fg_setmode(new_mode);                 fg_setmode(new_mode);
  4169.  
  4170.         max_x = fg_getmaxx();                 max_x = fg_getmaxx();
  4171.         max_y = fg_getmaxy();                 max_y = fg_getmaxy();
  4172.         mid_x = max_x / 2;                    mid_x = max_x / 2;
  4173.         mid_y = max_y / 2;                    mid_y = max_y / 2;
  4174.  
  4175.         fg_setcolor(15);                      fg_setcolor(15);
  4176.         fg_move(mid_x,0);                     fg_move(mid_x,0);
  4177.         fg_draw(mid_x,max_y);                 fg_drawrel(0,max_y);
  4178.         fg_move(0,mid_y);                     fg_moverel(-mid_x,-mid_y);
  4179.         fg_draw(max_x,mid_y);                 fg_drawrel(max_x,0);
  4180.         fg_waitkey();                         fg_waitkey();
  4181.  
  4182.         fg_setmode(old_mode);                 fg_setmode(old_mode);
  4183.         fg_reset();                           fg_reset();
  4184.      }                                     }
  4185.  
  4186.  
  4187.  
  4188.      Examples 6-4 and 6-5 are variations of example 6-2.  Example 6-4 uses
  4189. world space rather than screen space to draw the crossed lines.  Example 6-5
  4190. is the same as example 6-2 except it defines a clipping area to restrict
  4191. drawing to the upper left quadrant of the screen.  The clipping suppresses
  4192. the right half of the horizontal line and the lower half of the vertical
  4193. line.
  4194.                                          Chapter 6:  Graphics Fundamentals  81
  4195.  
  4196.                Example 6-4.                                Example 6-5.
  4197.  
  4198.   #include <fastgraf.h>                          #include <fastgraf.h>
  4199.   void main(void);                               void main(void);
  4200.  
  4201.   void main()                                    void main()
  4202.   {                                              {
  4203.      int new_mode, old_mode;                        int max_x, max_y;
  4204.                                                     int mid_x, mid_y;
  4205.      old_mode = fg_getmode();                       int new_mode, old_mode;
  4206.      new_mode = fg_automode();
  4207.      fg_setmode(new_mode);                          old_mode = fg_getmode();
  4208.      fg_initw();                                    new_mode = fg_automode();
  4209.      fg_setworld(-10.0,10.0,-10.0,10.0);            fg_setmode(new_mode);
  4210.  
  4211.      fg_setcolor(15);                               max_x = fg_getmaxx();
  4212.      fg_movew(0.0,10.0);                            max_y = fg_getmaxy();
  4213.      fg_draww(0.0,-10.0);                           mid_x = max_x / 2;
  4214.      fg_movew(-10.0,0.0);                           mid_y = max_y / 2;
  4215.      fg_draww(10.0,0.0);
  4216.      fg_waitkey();                                  fg_setclip(0,mid_x,0,mid_y);
  4217.  
  4218.      fg_setmode(old_mode);                          fg_setcolor(15);
  4219.      fg_reset();                                    fg_move(mid_x,0);
  4220.   }                                                 fg_draw(mid_x,max_y);
  4221.                                                     fg_move(0,mid_y);
  4222.                                                     fg_draw(max_x,mid_y);
  4223.                                                     fg_waitkey();
  4224.  
  4225.                                                     fg_setmode(old_mode);
  4226.                                                     fg_reset();
  4227.                                                  }
  4228.  
  4229. 82  Fastgraph User's Guide
  4230.  
  4231.  
  4232. Dashed Lines
  4233.  
  4234.      Fastgraph includes four routines for drawing dashed lines.  All four
  4235. routines draw lines in the current color value (as determined by the most
  4236. recent call to fg_setcolor) and observe the clipping limits.  The fg_dash
  4237. routine draws a dashed line from the current graphics cursor position to an
  4238. absolute screen space position, while the fg_dashw routine draws a dashed
  4239. line to an absolute world space position.  The fg_dashrel routine draws a
  4240. dashed line from the current graphics cursor position to a screen space
  4241. position relative to it.  The fg_dashrw routine does the same in world space.
  4242.  
  4243.      Each of these routines has three arguments.  The first two specify the
  4244. (x,y) coordinates of the destination position.  For the screen space
  4245. routines, these arguments are integer quantities.  For the world space
  4246. routines, these arguments are floating point quantities.  The third argument
  4247. is a 16-bit pattern that defines the appearance of the dashed line.  Bits
  4248. that are set in the pattern produce the visible part of the line, while bits
  4249. that are reset produce the invisible part.  This pattern is repeated as
  4250. necessary to draw the entire line.  For example, the pattern value 3333 hex
  4251. would produce a dashed line with the first two pixels off, the next two on,
  4252. the next two off, and so forth.  Similarly, the pattern value FFFF hex would
  4253. produce a solid line.
  4254.  
  4255.      The destination position passed to any of the dashed line routines
  4256. becomes the new graphics cursor position.  This makes it possible to draw
  4257. connected dashed lines without calling a graphics cursor movement routine
  4258. between successive calls to a line drawing routine.
  4259.  
  4260.      Example 6-6 draws a pair of crossed dashed lines that divide the screen
  4261. into quadrants.  It does this using the fg_move and fg_dash routines and
  4262. draws the lines in bright white, the default for color 15 in all graphics
  4263. video modes.  The dash pattern for each line is 3333 hex, which alternates
  4264. two pixels off and on.
  4265.  
  4266.                                  Example 6-6.
  4267.  
  4268.                        #include <fastgraf.h>
  4269.                        void main(void);
  4270.  
  4271.                        void main()
  4272.                        {
  4273.                           int max_x, max_y;
  4274.                           int mid_x, mid_y;
  4275.                           int new_mode, old_mode;
  4276.  
  4277.                           old_mode = fg_getmode();
  4278.                           new_mode = fg_automode();
  4279.                           fg_setmode(new_mode);
  4280.  
  4281.                           max_x = fg_getmaxx();
  4282.                           max_y = fg_getmaxy();
  4283.                           mid_x = max_x / 2;
  4284.  
  4285.                                          Chapter 6:  Graphics Fundamentals  83
  4286.  
  4287.                           mid_y = max_y / 2;
  4288.  
  4289.                           fg_setcolor(15);
  4290.                           fg_move(mid_x,0);
  4291.                           fg_dash(mid_x,max_y,0x3333);
  4292.                           fg_move(0,mid_y);
  4293.                           fg_dash(max_x,mid_y,0x3333);
  4294.                           fg_waitkey();
  4295.  
  4296.                           fg_setmode(old_mode);
  4297.                           fg_reset();
  4298.                        }
  4299.  
  4300. Polygons, Circles, and Ellipses
  4301.  
  4302.      Fastgraph includes routines for drawing three types of closed shapes:
  4303. polygons, circles, and ellipses.  Both screen space and world space versions
  4304. of these routines are available.  All the routines for drawing closed shapes
  4305. observe the clipping limits.
  4306.  
  4307.      The fg_polygon routine draws an unfilled polygon in screen space.
  4308. Fg_polygon requires an array of integer x coordinates as its first argument,
  4309. and an array of integer y coordinates as its second argument.  Each (x,y)
  4310. coordinate pair from the two arrays is treated as a polygon vertex.  In other
  4311. words, the x coordinate of the first polygon vertex is the first element of
  4312. the x coordinate array, and the y coordinate of the first vertex is the first
  4313. element of the y coordinate array.  Similarly, the second elements of each
  4314. array define the second vertex, and so forth.  The third argument for
  4315. fg_polygon is an integer quantity that specifies the number of elements in
  4316. the two coordinate arrays.
  4317.  
  4318.      Another routine, fg_polygonw, draws an unfilled polygon in world space.
  4319. The fg_polygonw routine is the same as the fg_polygon routine, except its x
  4320. and y coordinate arrays must contain floating point values instead of
  4321. integers.
  4322.  
  4323.      The drawing of the polygon begins at the graphics cursor position.  The
  4324. routine then draws a solid line in the current color to the first vertex,
  4325. then to the second vertex, and continues in this manner up to the last
  4326. vertex.  If necessary, fg_polygon and fg_polygonw draw a line connecting the
  4327. last vertex and the original graphics cursor position.  This last operation
  4328. closes the polygon and effectively leaves the graphics cursor position
  4329. unchanged.
  4330.  
  4331.      Example 6-7 illustrates the use of the fg_polygon routine in the EGA
  4332. monochrome or enhanced modes (modes 15 and 16).  The program exits if neither
  4333. of these video modes are available.
  4334.  
  4335.                                  Example 6-7.
  4336.  
  4337.              #include <fastgraf.h>
  4338.              #include <stdio.h>
  4339.              #include <stdlib.h>
  4340.              void main(void);
  4341.  
  4342.              #define VERTICES 10
  4343.  
  4344. 84  Fastgraph User's Guide
  4345.  
  4346.  
  4347.              int x[] = {200,300,400,400,300,240,160,160,200,200};
  4348.              int y[] = {100, 80,100,220,320,320,240,200,160,160};
  4349.  
  4350.              void main()
  4351.              {
  4352.                 int old_mode;
  4353.  
  4354.                 old_mode = fg_getmode();
  4355.  
  4356.                 if (fg_testmode(16,1))
  4357.                    fg_setmode(16);
  4358.                 else if (fg_testmode(15,1))
  4359.                    fg_setmode(15);
  4360.                 else {
  4361.                    printf("This program requires a 640 x 350 ");
  4362.                    printf("EGA graphics mode.\n");
  4363.                    exit(1);
  4364.                    }
  4365.  
  4366.                 fg_setcolor(1);
  4367.                 fg_polygon(x,y,VERTICES);
  4368.                 fg_waitkey();
  4369.  
  4370.                 fg_setmode(old_mode);
  4371.                 fg_reset();
  4372.              }
  4373.  
  4374.  
  4375.      The fg_circle routine draws an unfilled circle in screen space, centered
  4376. at the graphics cursor position, using the current color.  The routine's only
  4377. argument specifies the circle's radius in horizontal screen space units.
  4378. Another routine, fg_circlew, draws an unfilled circle where the radius is
  4379. measured in horizontal world space units.  Both routines leave the graphics
  4380. cursor position unchanged.
  4381.  
  4382.      The fg_ellipse routine draws an unfilled ellipse in screen space,
  4383. centered at the graphics cursor position, using the current color.  The
  4384. routine requires two arguments that respectively specify the length of its
  4385. horizontal and vertical semi-axes.  In other words, the first argument is the
  4386. absolute distance from the center of the ellipse to its horizontal extremity,
  4387. and the second argument is the absolute distance from the center of the
  4388. ellipse to its vertical extremity.  Another routine, fg_ellipsew, draws an
  4389. unfilled ellipse in world space.  Both routines leave the graphics cursor
  4390. position unchanged.
  4391.  
  4392.      Example 6-8 illustrates the use of the fg_circlew and fg_ellipsew
  4393. routines.  The program first uses the fg_automode routine to propose a
  4394. graphics video mode and then uses the fg_setmode routine to select that video
  4395. mode.  It then makes color 15 the current color, which by default is bright
  4396. white in all color graphics modes and "on" in the monochrome graphics modes.
  4397. Next, it establishes a 200-unit by 200-unit world space coordinate system.
  4398. The program then uses fg_ellipsew to draw an ellipse and fg_circlew to draw a
  4399. circle, both centered at the middle of the screen (which is the origin of our
  4400. world space coordinate system).  The circle has a radius of 1/16 the width of
  4401. the screen (12.5 horizontal world space units), and the ellipse is
  4402. horizontally inscribed within the circle.
  4403.                                          Chapter 6:  Graphics Fundamentals  85
  4404.  
  4405.      Example 6-9 illustrates the use of the fg_circle and fg_ellipse
  4406. routines.  It is functionally identical to the program of example 6-8, but it
  4407. uses screen space rather than world space coordinates to draw the circle and
  4408. ellipse.  Note the arguments to the fg_circle and fg_ellipse routines are
  4409. dependent on the maximum x and y coordinates of the selected video mode.  If
  4410. we didn't compute these arguments in this manner, the actual size of the
  4411. circle and ellipse would be proportional to the pixel resolution of the video
  4412. mode.  No such dependency exists when using world space, but we pay a price
  4413. for this feature in slightly slower execution speed.
  4414.  
  4415.                  Example 6-8.                               Example 6-9.
  4416.  
  4417.   #include <fastgraf.h>                         #include <fastgraf.h>
  4418.   void main(void);                              void main(void);
  4419.  
  4420.   void main()                                   void main()
  4421.   {                                             {
  4422.      int old_mode;                                 int mid_x, mid_y;
  4423.                                                    int old_mode;
  4424.      old_mode = fg_getmode();                      int x,y;
  4425.      fg_setmode(fg_automode());
  4426.      fg_setcolor(15);                              old_mode = fg_getmode();
  4427.                                                    fg_setmode(fg_automode());
  4428.      fg_initw();                                   fg_setcolor(15);
  4429.      fg_setworld(-100.0,100.0,-100.0,100.0);
  4430.                                                    mid_x = fg_getmaxx() / 2;
  4431.      fg_movew(0.0,0.0);                            mid_y = fg_getmaxy() / 2;
  4432.      fg_ellipsew(12.5,12.5);                       x = mid_x / 8;
  4433.      fg_circlew(12.5);                             y = mid_y / 8;
  4434.      fg_waitkey();
  4435.                                                    fg_move(mid_x,mid_y);
  4436.      fg_setmode(old_mode);                         fg_ellipse(x,y);
  4437.      fg_reset();                                   fg_circle(x);
  4438.   }                                                fg_waitkey();
  4439.  
  4440.                                                    fg_setmode(old_mode);
  4441.                                                    fg_reset();
  4442.                                                  }
  4443.  
  4444. 86  Fastgraph User's Guide
  4445.  
  4446.  
  4447. Solid Rectangles
  4448.  
  4449.      Fastgraph includes four routines for drawing solid rectangles, two for
  4450. screen space and two for world space, with and without clipping.  None of
  4451. these routines affect the graphics cursor position.
  4452.  
  4453.      The fg_rect routine draws a solid rectangle in screen space, without
  4454. regard to the clipping limits, using the current color.  Fg_rect requires
  4455. four integer arguments that respectively define the minimum x, maximum x,
  4456. minimum y, and maximum y screen space coordinates of the rectangle.  The
  4457. minimum coordinates must be less than or equal to the maximum coordinates, or
  4458. else the results are unpredictable.  The fg_clprect routine is identical in
  4459. all respects to the fg_rect routine, except it observes the clipping limits.
  4460.  
  4461.      The world space versions of the solid rectangle drawing routines are
  4462. fg_rectw and fg_clprectw.  Like fg_rect and fg_clprect, they require four
  4463. arguments that define the extremes of the rectangle, but the arguments are
  4464. floating point world space coordinates.
  4465.  
  4466.      You also can use the fg_rect routine in text modes.  When used in a text
  4467. mode, fg_rect expects its four arguments to be expressed in character space
  4468. (that is, rows and columns) rather than screen space.  This means the four
  4469. arguments respectively specify the minimum column, maximum column, minimum
  4470. row, and maximum row of the rectangle.  Fastgraph constructs the rectangle by
  4471. storing the solid block character (ASCII decimal value 219) in each character
  4472. cell comprising the rectangle.  The rectangle is drawn using the current
  4473. character attribute, but because the solid block character occupies the
  4474. entire character cell, the background component of the attribute is
  4475. essentially meaningless.
  4476.  
  4477.      Example 6-10 demonstrates the use of the fg_rect routine by drawing 200
  4478. random-size rectangles in random colors.  The program first uses the
  4479. fg_automode routine to propose a graphics video mode and then uses the
  4480. fg_setmode routine to select that video mode.  Next, it determines the
  4481. horizontal and vertical screen resolution for the selected video mode, using
  4482. the fg_getmaxx and fg_getmaxy routines.  The main part of the program is a
  4483. for loop that generates a random rectangle in each iteration.  Inside the
  4484. loop, the C library function rand is used to generate the extremes of the
  4485. rectangle.  If necessary, the program then exchanges the coordinates to make
  4486. the minimum coordinates less than or equal to the maximum coordinates.
  4487. Finally, it again uses rand to generate a random color number between 0 and
  4488. 15, and then draws the rectangle in that color.  After drawing all 200
  4489. rectangles, the program restores the original video mode and screen
  4490. attributes before returning to DOS.
  4491.                                          Chapter 6:  Graphics Fundamentals  87
  4492.  
  4493.                                 Example 6-10.
  4494.  
  4495.             #include <fastgraf.h>
  4496.             void main(void);
  4497.  
  4498.             #define RECTANGLES 200
  4499.             #define SWAP(a,b,temp) { temp = a; a = b; b = temp; }
  4500.  
  4501.             void main()
  4502.             {
  4503.                int i;
  4504.                int minx, maxx, miny, maxy;
  4505.                int old_mode;
  4506.                int temp;
  4507.                int xres, yres;
  4508.  
  4509.                old_mode = fg_getmode();
  4510.                fg_setmode(fg_automode());
  4511.  
  4512.                xres = fg_getmaxx() + 1;
  4513.                yres = fg_getmaxy() + 1;
  4514.  
  4515.                for (i = 0; i < RECTANGLES; i++) {
  4516.                   minx = rand() % xres;
  4517.                   maxx = rand() % xres;
  4518.                   miny = rand() % yres;
  4519.                   maxy = rand() % yres;
  4520.                   if (minx > maxx)
  4521.                      SWAP(minx,maxx,temp);
  4522.                   if (miny > maxy)
  4523.                      SWAP(miny,maxy,temp);
  4524.                   fg_setcolor(rand()%16);
  4525.                   fg_rect(minx,maxx,miny,maxy);
  4526.                   }
  4527.  
  4528.                fg_setmode(old_mode);
  4529.                fg_reset();
  4530.             }
  4531.  
  4532.  
  4533. Unfilled Rectangles
  4534.  
  4535.      Fastgraph includes a routine for drawing unfilled rectangles.  The
  4536. fg_box routine draws an unfilled rectangle in screen space, with regard to
  4537. the clipping limits, using the current color.  The arguments to fg_box are
  4538. the same as those for fg_rect.  The depth of the rectangle's edges is one
  4539. pixel by default, but you can change the depth by calling fg_boxdepth.  The
  4540. fg_boxdepth routine expects two arguments.  The first argument is the width
  4541. of the rectangle's left and right sides, while the second is the height of
  4542. its top and bottom sides.  Once you call fg_boxdepth, fg_box draws all
  4543. unfilled rectangles using the depth values specified in the most recent call
  4544. to fg_boxdepth.  Unlike fg_rect, the fg_box routine has no effect in text
  4545. video modes.
  4546.  
  4547.      Example 6-11 is the same as example 6-10, but it draws unfilled instead
  4548. of solid rectangles.  The program uses fg_box to draw the each rectangle and
  4549. fg_boxdepth to define the rectangle depth at three pixels in each direction.
  4550. 88  Fastgraph User's Guide
  4551.  
  4552. Note that you don't need to call fg_boxdepth for each rectangle if you want
  4553. all of them to have the same depth.
  4554.  
  4555.                                 Example 6-11.
  4556.  
  4557.             #include <fastgraf.h>
  4558.             void main(void);
  4559.  
  4560.             #define RECTANGLES 200
  4561.             #define SWAP(a,b,temp) { temp = a; a = b; b = temp; }
  4562.  
  4563.             void main()
  4564.             {
  4565.                int i;
  4566.                int minx, maxx, miny, maxy;
  4567.                int old_mode;
  4568.                int temp;
  4569.                int xres, yres;
  4570.  
  4571.                old_mode = fg_getmode();
  4572.                fg_setmode(fg_automode());
  4573.                fg_boxdepth(3,3);
  4574.  
  4575.                xres = fg_getmaxx() + 1;
  4576.                yres = fg_getmaxy() + 1;
  4577.  
  4578.                for (i = 0; i < RECTANGLES; i++) {
  4579.                   minx = rand() % xres;
  4580.                   maxx = rand() % xres;
  4581.                   miny = rand() % yres;
  4582.                   maxy = rand() % yres;
  4583.                   if (minx > maxx)
  4584.                      SWAP(minx,maxx,temp);
  4585.                   if (miny > maxy)
  4586.                      SWAP(miny,maxy,temp);
  4587.                   fg_setcolor(rand()%16);
  4588.                   fg_box(minx,maxx,miny,maxy);
  4589.                   }
  4590.  
  4591.                fg_setmode(old_mode);
  4592.                fg_reset();
  4593.             }
  4594.  
  4595.  
  4596. Dithered Rectangles
  4597.  
  4598.      The process of alternating different color pixels across a region of the
  4599. display area is called dithering.  This technique is especially useful in the
  4600. graphics modes with few colors, such as CGA and Hercules modes, because you
  4601. can simulate additional colors through effective uses of dithering.
  4602. Fastgraph includes two routines for drawing dithered rectangles, one for
  4603. screen space and one for world space.  Neither routine observes the clipping
  4604. limits, nor do they affect the graphics cursor position.
  4605.  
  4606.      The fg_drect routine draws a dithered rectangle in screen space.  Like
  4607. the fg_rect routine, fg_drect requires four integer arguments that
  4608. respectively define the minimum x, maximum x, minimum y, and maximum y screen
  4609.                                          Chapter 6:  Graphics Fundamentals  89
  4610.  
  4611. space coordinates of the rectangle.  The minimum coordinates must be less
  4612. than or equal to the maximum coordinates, or else the results are
  4613. unpredictable.  However, fg_drect also requires a fifth argument that defines
  4614. the dithering matrix, which in turn determines the pixel pattern used to
  4615. build the dithered rectangle.  The size and format of the dithering matrix
  4616. are dependent on the video mode.
  4617.  
  4618.      The world space version of the dithered rectangle drawing routine is
  4619. fg_drectw.  Like fg_drect, it requires four arguments that define the
  4620. extremes of the rectangle, and a fifth argument that defines the dithering
  4621. matrix.
  4622.  
  4623.      As mentioned earlier, the size and format of the dithering matrix are
  4624. dependent on the video mode.  The dithering matrix is a four byte array in
  4625. all video modes except the 256 color graphics modes (modes 19 through 23),
  4626. where it is an eight byte array.  This array contains a pixel pattern that
  4627. fg_drect or fg_drectw replicates across the rectangle's area.  The structure
  4628. of the dithering matrix closely mimics the structure of video memory in each
  4629. graphics mode.
  4630.  
  4631.      The remainder of this section will present some simple mode-specific
  4632. examples to illustrate the structure of the dithering matrix in the different
  4633. graphics modes.  Suppose we would like to produce a "checkerboard" of light
  4634. blue and bright white pixels.  That is, in a given row of a rectangle,
  4635. consecutive pixels will alternate between these two colors.  Additionally,
  4636. the pattern for adjacent rows will be shifted such that there will always be
  4637. a bright white pixel above and below a light blue pixel, and vice versa.
  4638. Hence this pixel pattern would look something like
  4639.  
  4640.                                    B W B W
  4641.                                    W B W B
  4642.                                    B W B W
  4643.                                    W B W B
  4644.  
  4645. where each B represents a light blue pixel, and each W represents a bright
  4646. white pixel.  The following examples describe the dithering matrix that could
  4647. be used to produce such a pixel pattern in each graphics mode.
  4648.  
  4649. CGA Four-Color Graphics Modes
  4650.  
  4651.      The CGA four-color graphics modes (modes 4 and 5) use a four-byte
  4652. dithering matrix that Fastgraph treats as a four-row by one-column array.
  4653. Since each pixel in these modes requires two bits of video memory, each byte
  4654. of the dithering matrix holds four pixels.  Thus, the pixel representation of
  4655. the dithering matrix would appear as shown below on the left; its translation
  4656. to numeric values appears on the right.
  4657.  
  4658.                    [3]   B W B W       [3]   01 11 01 11
  4659.  
  4660.                    [2]   W B W B       [2]   11 01 11 01
  4661.  
  4662.                    [1]   B W B W       [1]   01 11 01 11
  4663.  
  4664.                    [0]   W B W B       [0]   11 01 11 01
  4665.  
  4666. 90  Fastgraph User's Guide
  4667.  
  4668. Because these modes do not offer a light blue color, we've used light cyan
  4669. (color value 1 in palette 1) to approximate light blue.  The B pixels thus
  4670. translate to color value 1, or 01 binary.  Bright white is available as color
  4671. value 3 in palette 1, so the W pixels translate to color value 3, or 11
  4672. binary.  The hexadecimal equivalent of the binary value 11011101 (for array
  4673. elements [0] and [2]) is DD, and the hexadecimal equivalent of the binary
  4674. value 01110111 (for array elements [1] and [3]) is 77.  As shown in example
  4675. 6-12, these are precisely the values assigned to the elements of the
  4676. dithering matrix.
  4677.  
  4678.      Example 6-12 uses mode 4 to display a 50-pixel by 50-pixel dithered
  4679. rectangle in the upper left corner of the screen.  The dithering matrix
  4680. represents the blue and white checkerboard pattern discussed in the preceding
  4681. paragraph.
  4682.  
  4683.                                 Example 6-12.
  4684.  
  4685.                        #include <fastgraf.h>
  4686.                        void main(void);
  4687.  
  4688.                        void main()
  4689.                        {
  4690.                           char matrix[4];
  4691.                           int old_mode;
  4692.  
  4693.                           old_mode = fg_getmode();
  4694.                           fg_setmode(4);
  4695.  
  4696.                           matrix[0] = matrix[2] = 0xDD;
  4697.                           matrix[1] = matrix[3] = 0x77;
  4698.                           fg_drect(0,49,0,49,matrix);
  4699.                           fg_waitkey();
  4700.  
  4701.                           fg_setmode(old_mode);
  4702.                           fg_reset();
  4703.                        }
  4704.  
  4705.  
  4706. CGA Two-Color Graphics Mode
  4707.  
  4708.      The CGA two-color graphics mode (mode 6) uses a four-byte dithering
  4709. matrix that Fastgraph treats as a four-row by one-column array, as in the
  4710. other four-color CGA modes.  However, each pixel in this mode only requires
  4711. one bit of video memory, so each byte of the dithering matrix holds eight
  4712. pixels.  Thus, the pixel representation of the dithering matrix would appear
  4713. as shown below on the left; its translation to numeric values appears on the
  4714. right.
  4715.  
  4716.              [3]   B W B W B W B W       [3]   0 1 0 1 0 1 0 1
  4717.  
  4718.              [2]   W B W B W B W B       [2]   1 0 1 0 1 0 1 0
  4719.  
  4720.              [1]   B W B W B W B W       [1]   0 1 0 1 0 1 0 1
  4721.  
  4722.              [0]   W B W B W B W B       [0]   1 0 1 0 1 0 1 0
  4723.  
  4724.                                          Chapter 6:  Graphics Fundamentals  91
  4725.  
  4726. Mode 6 obviously does not offer a light blue color, so we've used black
  4727. (color value 0) in its place.  The B pixels thus translate to color value 0.
  4728. Bright white is available as color value 1, so the W pixels translate to
  4729. color value 1.  The hexadecimal equivalent of the binary value 10101010 (for
  4730. array elements [0] and [2]) is AA, and the hexadecimal equivalent of the
  4731. binary value 01010101 (for array elements [1] and [3]) is 55.  Thus, to make
  4732. example 6-12 run in mode 6, we only need to change the fg_setmode argument
  4733. from 4 to 6 and change the dithering matrix values as shown below.
  4734.  
  4735.                         matrix[0] = matrix[2] = 0xAA;
  4736.                         matrix[1] = matrix[3] = 0x55;
  4737.  
  4738.  
  4739. Tandy/PCjr 16-Color Graphics Mode
  4740.  
  4741.      The Tandy/PCjr 16-color graphics mode (mode 9) also uses a four-byte
  4742. dithering matrix that Fastgraph treats as a four-row by one-column array.
  4743. Each pixel in this mode requires four bits of video memory, so each byte of
  4744. the dithering matrix only holds two pixels.  Thus, the pixel representation
  4745. of the dithering matrix would appear as shown below on the left; its
  4746. translation to numeric values appears on the right.
  4747.  
  4748.                       [3]   B W       [3]   1001 1111
  4749.  
  4750.                       [2]   W B       [2]   1111 1001
  4751.  
  4752.                       [1]   B W       [1]   1001 1111
  4753.  
  4754.                       [0]   W B       [0]   1111 1001
  4755.  
  4756. The B pixels translate to color value 9 (light blue), or 1001 binary, and the
  4757. W pixels translate to color value 15 (bright white), or 1111 binary.  The
  4758. hexadecimal equivalent of the binary value 11111001 (for array elements [0]
  4759. and [2]) is F9, and the hexadecimal equivalent of the binary value 10011111
  4760. (for array elements [1] and [3]) is 9F.  Thus, to make example 6-12 run in
  4761. mode 9, we only need to change the fg_setmode argument from 4 to 9 and change
  4762. the dithering matrix values as shown below.
  4763.  
  4764.                         matrix[0] = matrix[2] = 0xF9;
  4765.                         matrix[1] = matrix[3] = 0x9F;
  4766.  
  4767.  
  4768. Hercules Graphics Mode
  4769.  
  4770.      The size and format of the dithering matrix in the Hercules graphics
  4771. mode (mode 11) are the same as in the CGA two-color mode (mode 6).  Please
  4772. refer to page 90 for a discussion of mode 6 dithering.
  4773.  
  4774. Hercules Low-Resolution Graphics Mode
  4775.  
  4776.      The size and format of the dithering matrix in the Hercules low-
  4777. resolution graphics mode (mode 12) are the same as in the CGA four-color
  4778. modes (modes 4 and 5).  As far as our checkerboard example goes, we'll use
  4779. black (color value 0) in place of light blue, and bold (color value 3)
  4780. 92  Fastgraph User's Guide
  4781.  
  4782. instead of bright white.  Thus, the B pixels translate to 00 binary, while
  4783. the W pixels translate to 11 binary.  The hexadecimal equivalent of the
  4784. binary value 11001100 (for array elements [0] and [2]) is CC, and the
  4785. hexadecimal equivalent of the binary value 00110011 (for array elements [1]
  4786. and [3]) is 33.  Thus, to make example 6-12 run in mode 12, we only need to
  4787. change the fg_setmode argument from 4 to 12 and change the dithering matrix
  4788. values as shown below.
  4789.  
  4790.                         matrix[0] = matrix[2] = 0xCC;
  4791.                         matrix[1] = matrix[3] = 0x33;
  4792.  
  4793.  
  4794. EGA and VGA Graphics Modes
  4795.  
  4796.      The native EGA and VGA graphics modes (modes 13 through 18) use a four-
  4797. byte dithering matrix that Fastgraph treats as a four-row by one-column
  4798. array.  Unlike the other graphics modes, which allow you to store pixels of
  4799. several colors in the dithering matrix, the EGA and VGA modes treat the
  4800. dithering matrix as a bit map for a specific color.  Since each color in the
  4801. dither pattern must be stored in a separate bit map (that is, in a separate
  4802. dithering matrix), you must call fg_drect once for each color.  Furthermore,
  4803. you must use the fg_setcolor routine before each call to fg_drect to define
  4804. the color used with the dithering matrix.
  4805.  
  4806.      In all EGA and VGA graphics modes, each byte of the dithering matrix is
  4807. a bit map that represents eight pixels.  Using our familiar checkerboard
  4808. example, the pixel representation of the dithering matrix would appear as
  4809. shown below.
  4810.  
  4811.                            [3]   B W B W B W B W
  4812.  
  4813.                            [2]   W B W B W B W B
  4814.  
  4815.                            [1]   B W B W B W B W
  4816.  
  4817.                            [0]   W B W B W B W B
  4818.  
  4819. Translating this pattern to numeric values is simple.  Just construct one
  4820. dithering matrix for each color in the pattern (there are two colors in this
  4821. example), where pixels of the current color translate to 1, and other pixels
  4822. translate to 0.  Following our example, the translation for the B pixels
  4823. appears below on the left, while the translation for the W pixels appears on
  4824. the right.
  4825.  
  4826.              [3]   1 0 1 0 1 0 1 0       [3]   0 1 0 1 0 1 0 1
  4827.  
  4828.              [2]   0 1 0 1 0 1 0 1       [2]   1 0 1 0 1 0 1 0
  4829.  
  4830.              [1]   1 0 1 0 1 0 1 0       [1]   0 1 0 1 0 1 0 1
  4831.  
  4832.              [0]   0 1 0 1 0 1 0 1       [0]   1 0 1 0 1 0 1 0
  4833.  
  4834.                                          Chapter 6:  Graphics Fundamentals  93
  4835.  
  4836. The hexadecimal equivalent of the binary value 01010101 is 55, and the
  4837. hexadecimal equivalent of the binary value 10101010 is AA.  As shown in
  4838. example 6-13, these are precisely the values assigned to the elements of the
  4839. dithering matrices.
  4840.  
  4841.      Example 6-13 uses mode 13 to display our light blue and bright white
  4842. checkerboard pattern.  Note you must call fg_drect twice -- once for the
  4843. light blue pixels (color value 9), and again for the bright white pixels
  4844. (color value 15).  Note also how fg_setcolor is used before each call to
  4845. fg_drect to define the color of the pixels fg_drect will display.
  4846.  
  4847.                                 Example 6-13.
  4848.  
  4849.                        #include <fastgraf.h>
  4850.                        void main(void);
  4851.  
  4852.                        void main()
  4853.                        {
  4854.                           char matrix[4];
  4855.                           int old_mode;
  4856.  
  4857.                           old_mode = fg_getmode();
  4858.                           fg_setmode(13);
  4859.  
  4860.                           matrix[0] = matrix[2] = 0x55;
  4861.                           matrix[1] = matrix[3] = 0xAA;
  4862.                           fg_setcolor(9);
  4863.                           fg_drect(0,49,0,49,matrix);
  4864.  
  4865.                           matrix[0] = matrix[2] = 0xAA;
  4866.                           matrix[1] = matrix[3] = 0x55;
  4867.                           fg_setcolor(15);
  4868.                           fg_drect(0,49,0,49,matrix);
  4869.                           fg_waitkey();
  4870.  
  4871.                           fg_setmode(old_mode);
  4872.                           fg_reset();
  4873.                        }
  4874.  
  4875. MCGA and VGA 256-Color Graphics Modes
  4876.  
  4877.      The MCGA and VGA 256-color graphics modes (modes 19 through 23) use an
  4878. eight-byte dithering matrix that Fastgraph treats as a four-row by two-column
  4879. array.  Each pixel in these modes requires eight bits of video memory, so
  4880. each byte of the dithering matrix only holds a single pixel.  We therefore
  4881. need the two column dithering matrix to produce any type of dither pattern.
  4882. The pixel representation of the dithering matrix would appear as shown below
  4883. on the left; its translation to numeric values appears on the right.
  4884.  
  4885.                     [6]   B   W   [7]     [6]    9   15   [7]
  4886.  
  4887.                     [4]   W   B   [5]     [4]   15    9   [5]
  4888.  
  4889.                     [2]   B   W   [3]     [2]    9   15   [3]
  4890.  
  4891.                     [0]   W   B   [1]     [0]   15    9   [1]
  4892. 94  Fastgraph User's Guide
  4893.  
  4894.  
  4895. The B pixels translate to color value 9 (light blue), and the W pixels
  4896. translate to color value 15 (bright white).  Example 6-14 uses mode 19 to
  4897. draw our light blue and bright white checkerboard pattern.
  4898.  
  4899.                                 Example 6-14.
  4900.  
  4901.             #include <fastgraf.h>
  4902.             void main(void);
  4903.  
  4904.             void main()
  4905.             {
  4906.                char matrix[8];
  4907.                int old_mode;
  4908.  
  4909.                old_mode = fg_getmode();
  4910.                fg_setmode(19);
  4911.  
  4912.                matrix[0] = matrix[3] = matrix[4] = matrix[7] = 15;
  4913.                matrix[1] = matrix[2] = matrix[5] = matrix[6] =  9;
  4914.                fg_drect(0,49,0,49,matrix);
  4915.                fg_waitkey();
  4916.  
  4917.                fg_setmode(old_mode);
  4918.                fg_reset();
  4919.             }
  4920.  
  4921.  
  4922. Closing Remarks
  4923.  
  4924.      There are two other important items pertaining to the fg_drect and
  4925. fg_drectw routines.  These items apply regardless of which graphics video
  4926. mode is being used.
  4927.  
  4928.      First, the dithering matrix may not contain virtual color values.  That
  4929. is, the pixel color values stored in the dithering matrix must be between 0
  4930. and the maximum color value for the current video mode.  If any color value
  4931. is redefined using the fg_defcolor routine, Fastgraph always ignores the
  4932. redefinition and instead uses the actual color value.  Note this does not
  4933. apply to palette registers or video DAC registers, because in these cases we
  4934. are redefining the color associated with a color value and not the color
  4935. value itself.
  4936.  
  4937.      Second, Fastgraph aligns the dithering matrix to specific pixel rows.
  4938. Fastgraph draws the dithered rectangle starting with the pixel row specified
  4939. by the rectangle's lower limit (the maximum y coordinate for fg_drect, or the
  4940. minimum y coordinate for fg_drectw) and proceeds upward until reaching the
  4941. rectangle's upper limit.  In all cases the dithering matrix used by fg_drect
  4942. and fg_drectw contains four rows.  If we let r represent the pixel row
  4943. corresponding to the rectangle's lower limit, then the first row used in the
  4944. dithering matrix is r modulo 4 (assuming the dithering matrix rows are
  4945. numbered 0 to 3).  This alignment enables you to use the same dithering
  4946. matrix in multiple calls to fg_drect and fg_drectw for building an object of
  4947. adjacent dithered rectangles (for example, an L-shaped area) and still have
  4948. the dither pattern match where the rectangles intersect.
  4949.                                          Chapter 6:  Graphics Fundamentals  95
  4950.  
  4951. Region Fill
  4952.  
  4953.      Fastgraph includes routines for filling arbitrary regions.  The fg_paint
  4954. routine fills a region with the current color value by specifying a screen
  4955. space point in the region's interior.  The fg_paintw routine also fills a
  4956. region, but it requires the interior point to be expressed in world space.
  4957. Neither routine changes the graphics cursor position.
  4958.  
  4959.      Each of these routines has two arguments that specify the (x,y)
  4960. coordinates of the interior point.  For the fg_paint routine, the arguments
  4961. are integer quantities.  For the fg_paintw routine, they are floating point
  4962. quantities.
  4963.  
  4964.      The region being filled must be a closed polygon whose boundary color is
  4965. different from that of the specified interior point.  The region may contain
  4966. holes (interior areas that will not be filled).  Fastgraph fills the region
  4967. by changing every interior pixel whose color is the same as the specified
  4968. interior point, to the current color.  If the interior point is already the
  4969. current color, the region fill routines do nothing.  It is important to note
  4970. the screen edges are not considered polygon boundaries, and filling an open
  4971. polygon will cause the fg_paint and fg_paintw routines to behave
  4972. unpredictably.
  4973.  
  4974.      Example 6-15 illustrates a simple use of the fg_paint routine in a 320
  4975. by 200 graphics mode.  The program uses fg_bestmode to select an available
  4976. video mode (if no 320 by 200 graphics mode is available, the program exits).
  4977. After establishing the selected video mode, the program uses the fg_move and
  4978. fg_drawrel routines to draw a hollow rectangle in color 10 and a hollow
  4979. diamond in color 9.  The diamond is drawn in the middle of the rectangle,
  4980. thus making it a hole with respect to the rectangle.  The program leaves
  4981. these shapes on the screen until a key is pressed.  At that time, it calls
  4982. the fg_paint routine to fill that part of the rectangle outside the diamond
  4983. with color 10.  After waiting for another keystroke, the program again uses
  4984. fg_paint to fill the interior of the diamond with color 15.  Finally, the
  4985. program waits for another keystroke, restores the original video mode and
  4986. screen attributes, and returns to DOS.
  4987.  
  4988.                                 Example 6-15.
  4989.  
  4990.              #include <fastgraf.h>
  4991.              #include <stdio.h>
  4992.              #include <stdlib.h>
  4993.              void main(void);
  4994.  
  4995.              void main()
  4996.              {
  4997.                 int old_mode, new_mode;
  4998.  
  4999.                 new_mode = fg_bestmode(320,200,1);
  5000.                 if (new_mode < 0) {
  5001.                    printf("This program requires a 320 x 200 ");
  5002.                    printf("graphics mode.\n");
  5003.                    exit(1);
  5004.                    }
  5005.  
  5006.                 old_mode = fg_getmode();
  5007.  
  5008. 96  Fastgraph User's Guide
  5009.  
  5010.                 fg_setmode(new_mode);
  5011.  
  5012.                 fg_setcolor(10);
  5013.                 fg_move(100,50);
  5014.                 fg_drawrel(120,0);
  5015.                 fg_drawrel(0,100);
  5016.                 fg_drawrel(-120,0);
  5017.                 fg_drawrel(0,-100);
  5018.  
  5019.                 fg_setcolor(9);
  5020.                 fg_move(160,80);
  5021.                 fg_drawrel(30,20);
  5022.                 fg_drawrel(-30,20);
  5023.                 fg_drawrel(-30,-20);
  5024.                 fg_drawrel(30,-20);
  5025.                 fg_waitkey();
  5026.  
  5027.                 fg_setcolor(10);
  5028.                 fg_paint(160,70);
  5029.                 fg_waitkey();
  5030.  
  5031.                 fg_setcolor(15);
  5032.                 fg_paint(160,100);
  5033.                 fg_waitkey();
  5034.  
  5035.                 fg_setmode(old_mode);
  5036.                 fg_reset();
  5037.              }
  5038.  
  5039.  
  5040.  
  5041. Summary of Fundamental Graphics Routines
  5042.  
  5043.      This section summarizes the functional descriptions of the Fastgraph
  5044. routines presented in this chapter.  More detailed information about these
  5045. routines, including their arguments and return values, may be found in the
  5046. Fastgraph Reference Manual.
  5047.  
  5048.      FG_BOX draws an unfilled rectangle in screen space, with respect to the
  5049. clipping region.  The width of the rectangle's edges is one pixel unless
  5050. changed with the fg_boxdepth routine.
  5051.  
  5052.      FG_BOXDEPTH defines the depth of rectangles drawn with the fg_box
  5053. routine.  The fg_setmode routine initializes the box depth to one pixel.
  5054.  
  5055.      FG_CIRCLE draws an unfilled circle in screen space.  The circle is
  5056. centered at the graphics cursor position.
  5057.  
  5058.      FG_CIRCLEW draws an unfilled circle in world space.  The circle is
  5059. centered at the graphics cursor position.
  5060.  
  5061.      FG_CLPRECT draws a solid (filled) rectangle in screen space, with
  5062. respect to the clipping region.
  5063.  
  5064.      FG_CLPRECTW draws a solid (filled) rectangle in world space, with
  5065. respect to the clipping region.
  5066.                                          Chapter 6:  Graphics Fundamentals  97
  5067.  
  5068.      FG_DASH draws a dashed line from the graphics cursor position to an
  5069. absolute screen space position.  It also makes the destination position the
  5070. new graphics cursor position.
  5071.  
  5072.      FG_DASHREL draws a dashed line from the graphics cursor position to a
  5073. screen space position relative to it.  It also makes the destination position
  5074. the new graphics cursor position.
  5075.  
  5076.      FG_DASHRW draws a dashed line from the graphics cursor position to a
  5077. world space position relative to it.  It also makes the destination position
  5078. the new graphics cursor position.
  5079.  
  5080.      FG_DASHW draws a dashed line from the graphics cursor position to an
  5081. absolute world space position.  It also makes the destination position the
  5082. new graphics cursor position.
  5083.  
  5084.      FG_DRAW draws a solid line from the graphics cursor position to an
  5085. absolute screen space position.  It also makes the destination position the
  5086. new graphics cursor position.
  5087.  
  5088.      FG_DRAWREL draws a solid line from the graphics cursor position to a
  5089. screen space position relative to it.  It also makes the destination position
  5090. the new graphics cursor position.
  5091.  
  5092.      FG_DRAWRW draws a solid line from the graphics cursor position to a
  5093. world space position relative to it.  It also makes the destination position
  5094. the new graphics cursor position.
  5095.  
  5096.      FG_DRAWW draws a solid line from the graphics cursor position to an
  5097. absolute world space position.  It also makes the destination position the
  5098. new graphics cursor position.
  5099.  
  5100.      FG_DRECT draws a dithered rectangle in screen space, without regard to
  5101. the clipping region.  The rectangle's dither pattern is defined through a
  5102. dithering matrix whose format is dependent on the video mode being used.
  5103.  
  5104.      FG_DRECTW draws a dithered rectangle in world space, without regard to
  5105. the clipping region.  The rectangle's dither pattern is defined through a
  5106. dithering matrix whose format is dependent on the video mode being used.
  5107.  
  5108.      FG_ELLIPSE draws an unfilled ellipse in screen space.  The ellipse is
  5109. centered at the graphics cursor position, and its size is determined by the
  5110. specified lengths of the semi-axes.
  5111.  
  5112.      FG_ELLIPSEW draws an unfilled ellipse in world space.  The ellipse is
  5113. centered at the graphics cursor position, and its size is determined by the
  5114. specified lengths of the semi-axes.
  5115.  
  5116.      FG_ERASE clears the screen in either text or graphics modes.
  5117.  
  5118.      FG_GETPIXEL returns the color value of a specified pixel.
  5119.  
  5120.      FG_GETXPOS returns the screen space x coordinate of the graphics cursor
  5121. position.
  5122.  
  5123.      FG_GETYPOS returns the screen space y coordinate of the graphics cursor
  5124. position.
  5125. 98  Fastgraph User's Guide
  5126.  
  5127.      FG_MOVE establishes the graphics cursor position at an absolute screen
  5128. space point.
  5129.  
  5130.      FG_MOVEREL establishes the graphics cursor position at a screen space
  5131. point relative to the current position.
  5132.  
  5133.      FG_MOVERW establishes the graphics cursor position at a world space
  5134. point relative to the current position.
  5135.  
  5136.      FG_MOVEW establishes the graphics cursor position at an absolute world
  5137. space point.
  5138.  
  5139.      FG_PAINT fills an arbitrary closed region with the current color value.
  5140. The region is defined by specifying a screen space point within its interior.
  5141.  
  5142.      FG_PAINTW fills an arbitrary closed region with the current color value.
  5143. The region is defined by specifying a world space point within its interior.
  5144.  
  5145.      FG_POINT draws a point (that is, displays a pixel) in screen space.
  5146.  
  5147.      FG_POINTW draws a point in world space.
  5148.  
  5149.      FG_POLYGON draws an unfilled polygon in screen space, using two
  5150. coordinate arrays to define the polygon vertices.  The drawing of the polygon
  5151. begins at the graphics cursor position, through the vertices defined by the
  5152. coordinate arrays, and finally back to the original cursor position if
  5153. necessary.
  5154.  
  5155.      FG_POLYGONW draws an unfilled polygon in world space.  It is the same as
  5156. the fg_polygon routine, except the coordinate arrays contain world space
  5157. values.
  5158.  
  5159.      FG_RECT draws a solid (filled) rectangle in screen space or character
  5160. space, without regard to the clipping region.
  5161.  
  5162.      FG_RECTW draws a solid (filled) rectangle in world space, without regard
  5163. to the clipping region.
  5164.  
  5165.      FG_SETCLIP defines the clipping region in screen space.  The clipping
  5166. region is a rectangular area outside of which graphics are suppressed.
  5167.  
  5168.      FG_SETCLIPW defines the clipping region in world space.
  5169.  
  5170.  
  5171. Chapter 7
  5172.  
  5173. Character Display Routines
  5174. 100  Fastgraph User's Guide
  5175.  
  5176. Overview
  5177.  
  5178.      An important part of any program is the capability to display text or
  5179. other characters on the screen.  Fastgraph supports two character sets:  the
  5180. hardware or BIOS character set available with each video mode, and
  5181. Fastgraph's own software character set for graphics video modes.
  5182. Fastgraph/Light does not support the software character set.
  5183.  
  5184.      We'll begin this chapter with a review of character space, and then
  5185. discuss the specifics about hardware and software characters.  At the end of
  5186. the chapter, we'll briefly explain how to implement bit-mapped characters
  5187. into a program.  To simplify things, the example programs presented in this
  5188. chapter are mode-specific examples, and no testing is done to check if the
  5189. video mode is available on the user's system.
  5190.  
  5191.  
  5192. Character Space
  5193.  
  5194.      The coordinate system used for displaying hardware characters is called
  5195. character space.  It is the only coordinate system available in text video
  5196. modes, but it is a supplementary coordinate system you can use with either
  5197. screen space or world space in graphics video modes.  Character space can be
  5198. thought of as a grid of rows and columns, with each cell in the grid holding
  5199. one character.  Each cell is identified by its unique (row,column) integer
  5200. coordinates.  The rows and columns are numbered starting at zero; the origin
  5201. is always the upper left corner of the screen.  For example, in the 80-column
  5202. by 25-row video modes, the (row,column) coordinates of the screen corners are
  5203. shown in the following diagram.
  5204.  
  5205.                             (0,0)           (0,79)
  5206.  
  5207.                             (24,0)         (24,79)
  5208.  
  5209. The number of rows and columns depends on the video mode, as shown in the
  5210. following table.  For graphics modes, the table also includes the width and
  5211. height in pixels of a character cell.
  5212.  
  5213.                        Mode  No. of  No. of Char. Char.
  5214.                       Number Columns Rows   Width Height
  5215.  
  5216.                          4     40     25    8     8
  5217.                          5     40     25    8     8
  5218.                          6     80     25    8     8
  5219.                          9     40     25    8     8
  5220.                         11     80     25    9     14
  5221.                         12     40     25    8     8
  5222.                         13     40     25    8     8
  5223.                         14     80     25    8     8
  5224.                         15     80     25    8     14
  5225.                         16     80     25    8     14
  5226.                         17     80     30    8     16
  5227.                         18     80     30    8     16
  5228.                         19     40     25    8     8
  5229.                         20     40     25    8     8
  5230.                         21     40     50    8     8
  5231.                         22     40     30    8     8
  5232.                         23     40     60    8     8
  5233.                                    Chapter 7:  Character Display Routines  101
  5234.  
  5235.  
  5236. Hardware Characters
  5237.  
  5238.      Hardware characters are available in all of Fastgraph's supported video
  5239. modes.  As explained in Chapter 5, text mode characters have a display
  5240. attribute that defines their foreground color, their background color, and
  5241. whether or not they blink.  Graphics mode characters appear in a single
  5242. color, as determined by the current color index.  Chapter 5 also explained
  5243. how Fastgraph's fg_setattr and fg_setcolor routines define the attribute or
  5244. color index in which subsequent hardware characters appear.
  5245.  
  5246.      It is obviously important to define the color or attribute for hardware
  5247. characters, but it is equally important to define their location on the
  5248. screen.  Fastgraph draws hardware characters at the position defined by the
  5249. text cursor.  Like the graphics cursor, the text cursor is not a cursor in
  5250. the true sense, but is simply a pair of character space (row,column)
  5251. coordinates with a special meaning.  The fg_setmode routine sets the text
  5252. cursor position to the character space coordinates (0,0), which of course is
  5253. the upper left corner of the screen.(2)
  5254.  
  5255.      The Fastgraph routine fg_locate changes the text cursor position.  It
  5256. has two integer arguments that specify the (row,column) character space
  5257. coordinates of the new position.  The row values must be between 0 and one
  5258. less than the number of character rows available.  The column values must be
  5259. between 0 and one less than the number of character columns available.
  5260.  
  5261.      The fg_text routine is Fastgraph's basic character display routine.  It
  5262. displays a string of hardware characters, starting at the text cursor
  5263. position, using the current color attribute (for text modes) or color index
  5264. (for graphics modes).  If the string reaches the last column in a row,
  5265. fg_text will wrap the string to the first column of the next row.
  5266. Additionally, fg_text leaves the cursor one column to the right of the last
  5267. character displayed (or the first column of the next row if the last
  5268. character appears at the end of a row).  This feature makes it possible for
  5269. successive calls to fg_text to display adjacent strings.  The first argument
  5270. for the fg_text routine is a character string of arbitrary length, and the
  5271. second argument is an integer value that specifies the number of characters
  5272. to display from that string.
  5273.  
  5274.  
  5275.  
  5276. ____________________
  5277.  
  5278.      (2) In reality there are eight text cursors, one for each video page.
  5279. The fg_setmode routine initializes each text cursor position to (0,0).  The
  5280. next chapter describes this in more detail.
  5281. 102  Fastgraph User's Guide
  5282.  
  5283.      Example 7-1 illustrates the use of the fg_locate and fg_text routines in
  5284. the 80 by 25 color text mode (mode 3).  After establishing the video mode and
  5285. making the BIOS cursor invisible, the program displays four strings with
  5286. different attributes.  The attributes are selected using the fg_setattr
  5287. routine, and the strings are displayed by the fg_text routine.  The first
  5288. string appears in yellow (attributes 14,0,0) in the upper left corner of the
  5289. screen; the fg_locate routine is not necessary because (0,0) is the default
  5290. text cursor position established by fg_setmode.  The second string appears in
  5291. light green (10,0,0) one space to the right of the first string.  Its
  5292. position relies on the fact fg_text sets the new text cursor position one
  5293. space to the right of the last character displayed (following the "w" of
  5294. "yellow" in this case).  The leading space in " green" leaves a space between
  5295. the first and second strings.  Similarly, the third string appears in
  5296. blinking light red (12,0,1) one space to the right of the second string.
  5297.  
  5298.      The program then uses the fg_locate routine to move the text cursor to
  5299. the lower left corner of the screen and displays the "Press any key" string.
  5300. This string is displayed with a light red foreground against a gray
  5301. background (12,7,0).  The extra spaces surrounding the string extend the
  5302. background color one character position to the left and right and make the
  5303. string more visually appealing.  Finally, once you press any key, the program
  5304. restores the original video mode and screen attributes before returning to
  5305. DOS.
  5306.  
  5307.                                  Example 7-1.
  5308.  
  5309.                       #include <fastgraf.h>
  5310.                       void main(void);
  5311.  
  5312.                       void main()
  5313.                       {
  5314.                          int old_mode;
  5315.  
  5316.                          old_mode = fg_getmode();
  5317.                          fg_setmode(3);
  5318.                          fg_cursor(0);
  5319.  
  5320.                          fg_setattr(14,0,0);
  5321.                          fg_text("yellow",6);
  5322.  
  5323.                          fg_setattr(10,0,0);
  5324.                          fg_text(" green",6);
  5325.  
  5326.                          fg_setattr(12,0,1);
  5327.                          fg_text(" blinking",9);
  5328.  
  5329.                          fg_setattr(12,7,0);
  5330.                          fg_locate(24,0);
  5331.                          fg_text(" Press any key. ",16);
  5332.                          fg_waitkey();
  5333.  
  5334.                          fg_setmode(old_mode);
  5335.                          fg_reset();
  5336.                       }
  5337.  
  5338.      The fg_where routine retrieves the text cursor position in its two
  5339. integer arguments.  This routine is not used as frequently as the fg_locate
  5340.                                    Chapter 7:  Character Display Routines  103
  5341.  
  5342. and fg_text routines because more often than not your program will know the
  5343. text cursor position implicitly, or you'll know in advance the locations at
  5344. which text will be displayed.  The fg_where routine takes two integer
  5345. arguments passed as pointers (that is, by reference), and these two arguments
  5346. respectively receive the text cursor's current row and column position.
  5347.  
  5348.      Example 7-2 produces the same results as example 7-1, but it does so a
  5349. bit differently.  It uses its own routine, put_string, to display a string at
  5350. a specified row and column.  The put_string routine simply calls fg_locate to
  5351. establish the text cursor position and then calls fg_text to display the
  5352. string.  Note the use of the C library function strlen to determine the
  5353. string length passed to the fg_text routine.  Example 7-2 also uses the
  5354. fg_where routine to retrieve the new text cursor positions, which are then
  5355. passed to the put_string routine.
  5356.  
  5357.                                  Example 7-2.
  5358.  
  5359.                    #include <fastgraf.h>
  5360.                    #include <string.h>
  5361.                    void main(void);
  5362.                    void put_string(char*,int,int);
  5363.  
  5364.                    void main()
  5365.                    {
  5366.                       int old_mode;
  5367.                       int row, column;
  5368.  
  5369.                       old_mode = fg_getmode();
  5370.                       fg_setmode(3);
  5371.                       fg_cursor(0);
  5372.  
  5373.                       fg_setattr(14,0,0);
  5374.                       put_string("yellow",0,0);
  5375.  
  5376.                       fg_setattr(10,0,0);
  5377.                       fg_where(&row,&column);
  5378.                       put_string("green",row,column+1);
  5379.                       fg_setattr(12,0,1);
  5380.                       fg_where(&row,&column);
  5381.                       put_string("blinking",row,column+1);
  5382.  
  5383.                       fg_setattr(12,7,0);
  5384.                       put_string(" Press any key. ",24,0);
  5385.                       fg_waitkey();
  5386.  
  5387.                       fg_setmode(old_mode);
  5388.                       fg_reset();
  5389.                    }
  5390.  
  5391.                    void put_string(string,row,column)
  5392.                    char *string;
  5393.                    int row, column;
  5394.                    {
  5395.                       fg_locate(row,column);
  5396.                       fg_text(string,strlen(string));
  5397.                    }
  5398.  
  5399. 104  Fastgraph User's Guide
  5400.  
  5401.      Sometimes you may wish to change the display attribute of existing text,
  5402. such as when creating a shadow around the edges of a pop-up window.  The
  5403. Fastgraph routine fg_chgattr performs this function.  It applies the current
  5404. text display attribute (as defined in the most recent call to fg_setattr or
  5405. fg_setcolor) to a given number of characters, starting at the text cursor
  5406. position.  It leaves the text cursor one column to the right of the last
  5407. character changed (or the first column of the next row if the last character
  5408. is at the end of a row).  The fg_chgattr routine's argument specifies the
  5409. number of characters to change.  This routine has no effect in graphics video
  5410. modes.
  5411.  
  5412.      The Fastgraph routine fg_chgtext performs somewhat the opposite function
  5413. of fg_chgattr.  It displays new text but uses the display attributes already
  5414. assigned to the character cells where the text will appear.  The fg_chgtext
  5415. routine takes the same two arguments as the fg_text routine, displays the
  5416. characters starting at the text cursor position, and leaves the cursor one
  5417. column to the right of the last character displayed.  Like fg_chgattr,
  5418. fg_chgtext has no effect in graphics video modes.
  5419.  
  5420.      Example 7-3 illustrates the fg_chgattr and fg_chgtext routines.  It runs
  5421. in the 80-column color text mode (mode 3), but if we change the fg_setmode
  5422. argument it also would run in the monochrome text mode (mode 7).  The program
  5423. first displays the word "hello" in the upper left corner of the screen, using
  5424. a gray foreground and black background attribute.  After waiting for a
  5425. keystroke, the program calls fg_chgattr to make the word "hello" appear in
  5426. reverse video (that is, a black foreground and gray background attribute).
  5427. After a second keystroke, the program uses fg_chgtext to change the "h" of
  5428. "hello" to upper case.  Following this, the program returns to DOS.
  5429.  
  5430.                                  Example 7-3.
  5431.  
  5432.                          #include <fastgraf.h>
  5433.                          void main(void);
  5434.  
  5435.                          void main()
  5436.                          {
  5437.                             int old_mode;
  5438.  
  5439.                             old_mode = fg_getmode();
  5440.                             fg_setmode(3);
  5441.                             fg_cursor(0);
  5442.                             fg_setattr(7,0,0);
  5443.                             fg_text("hello",5);
  5444.                             fg_waitkey();
  5445.  
  5446.                             fg_locate(0,0);
  5447.                             fg_setattr(0,7,0);
  5448.                             fg_chgattr(5);
  5449.                             fg_waitkey();
  5450.                             fg_locate(0,0);
  5451.                             fg_chgtext("H",1);
  5452.                             fg_waitkey();
  5453.  
  5454.                             fg_setmode(old_mode);
  5455.                             fg_reset();
  5456.                          }
  5457.  
  5458.                                    Chapter 7:  Character Display Routines  105
  5459.  
  5460.  
  5461.      You also can retrieve the character or attribute stored in a specific
  5462. character cell.  The Fastgraph routine fg_getchar retrieves character values,
  5463. while fg_getattr retrieves character attributes.  Both routines have two
  5464. integer arguments that specify the (row,column) coordinates for the character
  5465. cell of interest.  Example 7-4 uses fg_getchar and fg_getattr to obtain the
  5466. character and attribute stored at row 24, column 0.  Just before the program
  5467. exits, it displays these values.
  5468.  
  5469.                                  Example 7-4.
  5470.  
  5471.                      #include <fastgraf.h>
  5472.                      #include <stdio.h>
  5473.                      void main(void);
  5474.  
  5475.                      void main()
  5476.                      {
  5477.                         int attr, value;
  5478.                         int old_mode;
  5479.  
  5480.                         old_mode = fg_getmode();
  5481.                         fg_setmode(3);
  5482.                         fg_cursor(0);
  5483.  
  5484.                         fg_setattr(9,7,0);
  5485.                         fg_locate(24,0);
  5486.                         fg_text("Test",4);
  5487.                         value = fg_getchar(24,0);
  5488.                         attr  = fg_getattr(24,0);
  5489.                         fg_waitkey();
  5490.  
  5491.                         fg_setmode(old_mode);
  5492.                         fg_reset();
  5493.                         printf("%c %2.2X\n",value,attr);
  5494.                      }
  5495.  
  5496.  
  5497.      If you need to retrieve characters and attributes from a rectangular
  5498. area, it's more efficient to use the fg_getimage routine (described in
  5499. Chapter 9) than to call fg_getchar and fg_getattr repeatedly.
  5500.  
  5501.      Displaying hardware characters in graphics video modes is quite
  5502. different from doing so in text modes, although we use the same Fastgraph
  5503. routines in both cases.  Example 7-5 is similar to example 7-1, but it runs
  5504. in the EGA enhanced graphics mode (mode 16) instead of a text mode.  In
  5505. graphics modes, the fg_cursor routine has no effect, so we have omitted it
  5506. from the program.  Furthermore, characters cannot be displayed with a
  5507. blinking attribute, so we have omitted the blinking characters (we could
  5508. simulate blinking by repetitively displaying and erasing them, but that is
  5509. beyond the scope of this example).  Because graphics mode characters only
  5510. have a foreground color, we had to simulate the gray background of the "Press
  5511. any key" string by first drawing a rectangle where that string appears.  The
  5512. differences between examples 7-5 and 7-1 hold for any graphics video mode,
  5513. not just mode 16.
  5514. 106  Fastgraph User's Guide
  5515.  
  5516.                                  Example 7-5.
  5517.  
  5518.                       #include <fastgraf.h>
  5519.                       void main(void);
  5520.  
  5521.                       void main()
  5522.                       {
  5523.                          int old_mode;
  5524.  
  5525.                          old_mode = fg_getmode();
  5526.                          fg_setmode(16);
  5527.  
  5528.                          fg_setcolor(14);
  5529.                          fg_text("yellow",6);
  5530.  
  5531.                          fg_setcolor(10);
  5532.                          fg_text(" green",6);
  5533.  
  5534.                          fg_setcolor(7);
  5535.                          fg_rect(0,127,336,349);
  5536.                          fg_setcolor(12);
  5537.                          fg_locate(24,0);
  5538.                          fg_text(" Press any key. ",16);
  5539.                          fg_waitkey();
  5540.  
  5541.                          fg_setmode(old_mode);
  5542.                          fg_reset();
  5543.                       }
  5544.  
  5545.      Example 7-6 demonstrates a side effect that occurs when displaying
  5546. characters in graphics modes.  This example uses the MCGA graphics mode (mode
  5547. 19) and displays two character strings at the same location.  If we were to
  5548. do this in a text mode, the first string would disappear once we displayed
  5549. the second string.  In graphics modes, however, the portions of the first
  5550. string not covered by characters from the second string are still visible.
  5551. The reason for this may not be clear at first, but remember when we display
  5552. characters in graphics modes, we aren't really displaying characters but
  5553. merely a pixel representation of the characters.  Fastgraph has no way to
  5554. distinguish such pixels from any other pixels.
  5555.  
  5556.                                  Example 7-6.
  5557.  
  5558.                          #include <fastgraf.h>
  5559.                          void main(void);
  5560.  
  5561.                          void main()
  5562.                          {
  5563.                             int old_mode;
  5564.  
  5565.                             old_mode = fg_getmode();
  5566.                             fg_setmode(19);
  5567.  
  5568.                             fg_setcolor(14);
  5569.                             fg_text("yellow",6);
  5570.                             fg_locate(0,0);
  5571.                             fg_setcolor(10);
  5572.  
  5573.                                    Chapter 7:  Character Display Routines  107
  5574.  
  5575.                             fg_text(" green",6);
  5576.                             fg_waitkey();
  5577.                             fg_setmode(old_mode);
  5578.                             fg_reset();
  5579.                          }
  5580.  
  5581.  
  5582.      To avoid this problem, the recommended procedure for displaying
  5583. characters in graphics modes is to first erase the area where the text will
  5584. appear.  The easiest way to do this is to use the fg_rect routine to draw a
  5585. rectangle in the background color.  In example 7-6, we could do this by
  5586. inserting the statements
  5587.  
  5588.                               fg_setcolor(0);
  5589.                               fg_rect(0,47,0,7);
  5590.  
  5591. immediately before the call to fg_locate.  The parameters passed to the
  5592. fg_rect routine represent the 48 by 8 pixel region that corresponds to the
  5593. first six character cells of row 0 in the 320 by 200 graphics modes.
  5594.  
  5595.  
  5596. Conversion Routines
  5597.  
  5598.      We have already mentioned Fastgraph includes routines for converting
  5599. coordinates between character space and screen space (see page 44).  In this
  5600. section, we will review these routines and then present an example that uses
  5601. some of them.
  5602.  
  5603.      The fg_xalpha and fg_yalpha routines convert screen space coordinates to
  5604. character space.  The fg_xalpha routine converts a screen space x coordinate
  5605. to the character space column that contains the coordinate.  Similarly, the
  5606. fg_yalpha routine converts a screen space y coordinate to the character space
  5607. row that contains the coordinate.
  5608.  
  5609.      The fg_xconvert and fg_yconvert routines convert character space
  5610. coordinates to screen space.  The fg_xconvert routine converts a character
  5611. space column to the screen space coordinate of its leftmost pixel.
  5612. Similarly, the fg_yconvert routine converts a character space row to the
  5613. screen space coordinate of its top (lowest-numbered) pixel.
  5614.  
  5615.      On page 105, example 7-5 demonstrated how to display characters in a
  5616. graphics mode.  Because characters do not have a background color in graphics
  5617. modes, example 7-5 used the fg_rect routine to simulate a background color by
  5618. drawing a gray rectangle before displaying the text.  It was necessary to
  5619. determine the screen coordinates of the character cells so we could pass the
  5620. correct parameters to fg_rect.  By using the fg_xconvert and fg_yconvert
  5621. routines, we can let Fastgraph calculate the required screen coordinates.
  5622. This method has the additional benefit of working in any graphics mode,
  5623. whereas the coordinates passed to fg_rect in example 7-5 would only work
  5624. properly in a 640 by 350 graphics mode.  Example 7-7 shows how we could
  5625. extend example 7-5 to use the fg_xconvert and fg_yconvert routines.
  5626.  
  5627.                                  Example 7-7.
  5628.  
  5629.                       #include <fastgraf.h>
  5630.                       void main(void);
  5631.  
  5632. 108  Fastgraph User's Guide
  5633.  
  5634.                       void main()
  5635.                       {
  5636.                          int old_mode;
  5637.                          int minx, maxx, miny, maxy;
  5638.  
  5639.                          fg_old_mode = fg_getmode();
  5640.                          fg_setmode(16);
  5641.  
  5642.                          fg_setcolor(14);
  5643.                          fg_text("yellow",6);
  5644.  
  5645.                          fg_setcolor(10);
  5646.                          fg_text(" green",6);
  5647.  
  5648.                          fg_setcolor(7);
  5649.                          minx = fg_xconvert(0);
  5650.                          maxx = fg_xconvert(16) - 1;
  5651.                          miny = fg_yconvert(24);
  5652.                          maxy = fg_yconvert(25) - 1;
  5653.                          fg_rect(minx,maxx,miny,maxy);
  5654.                          fg_setcolor(12);
  5655.                          fg_locate(24,0);
  5656.                          fg_text(" Press any key. ",16);
  5657.                          fg_waitkey();
  5658.  
  5659.                          fg_setmode(old_mode);
  5660.                          fg_reset();
  5661.                       }
  5662.  
  5663.  
  5664. Software Characters
  5665.  
  5666.      Software characters, also called stroke characters or vector characters
  5667. in other literature, are only are available in graphics video modes.  Unlike
  5668. the fixed-size hardware characters, you can display software characters in
  5669. any size, at any angle, and at any position.  In addition, software
  5670. characters are proportionally spaced.  However, software characters take
  5671. longer to draw than do hardware characters.
  5672.  
  5673.      Fastgraph includes two software character fonts, called the primary font
  5674. and the alternate font.  The primary font contains upper and lower case
  5675. letters, numbers, punctuation, and most of the other printable ASCII
  5676. characters.  The alternate font contains upper and lower case Greek letters
  5677. and other mathematical and scientific symbols.
  5678.  
  5679.      The Fastgraph routine fg_swchar displays a string of software characters
  5680. in the current color index (as defined by the most recent call to
  5681. fg_setcolor).  The string may contain any characters from the primary font,
  5682. the alternate font, or both.  You can display the characters left justified,
  5683. centered, or right justified relative to the graphics cursor position.  Just
  5684. as the fg_text routine updates the text cursor position, fg_swchar sets the
  5685. graphics cursor position just to the right of the last character drawn.  The
  5686. characters are clipped according to the current clipping region.  In addition
  5687. to the characters, the string passed to fg_swchar also may contain operators
  5688. for switching fonts, underlining, subscripting, or superscripting characters.
  5689. Because fg_swchar internally uses world space coordinates, you must call the
  5690. fg_initw routine at some point in your program before the first call to
  5691.                                    Chapter 7:  Character Display Routines  109
  5692.  
  5693. fg_swchar.  You also must establish a world space coordinate system with the
  5694. fg_setworld routine.
  5695.  
  5696.      The fg_swchar routine has three arguments.  The first argument is the
  5697. character string to display.  The second argument is an integer value that
  5698. specifies the number of characters in the string, including any characters
  5699. used as special operators.  The third argument is an integer value that
  5700. determines the position of the string relative to the graphics cursor
  5701. position.  If this value is negative, the lower left corner of the first
  5702. character will be at the graphics cursor position.  If it is positive, the
  5703. lower right corner of the last character will be at the graphics cursor
  5704. position.  If it is zero, the string will be horizontally centered at the
  5705. graphics cursor position.
  5706.  
  5707.      The size of software characters is determined by the values passed to
  5708. the fg_setsize, fg_setsizew, and fg_setratio routines.  The fg_setsize
  5709. routine has a single integer argument that defines the height of software
  5710. characters in screen space units, while the fg_setsizew routine has a single
  5711. floating point argument that defines the height in world space units.  If
  5712. neither of these routines is called, Fastgraph will use its default character
  5713. height of one world space unit.  The fg_setratio routine has a single
  5714. floating point argument that defines the aspect ratio for software
  5715. characters.  The aspect ratio is the ratio of character width to character
  5716. height.  For example, an aspect ratio of 2.0 means characters are twice as
  5717. wide as they are high.  If the fg_setratio routine is not called, Fastgraph
  5718. uses its default aspect ratio of 1.
  5719.  
  5720.      Example 7-8 displays both of the software character fonts.  The program
  5721. uses the enhanced EGA graphics mode (mode 16), but it could run in any
  5722. graphics mode by changing the fg_setmode argument.  After establishing the
  5723. video mode, the program calls the fg_initw routine to initialize Fastgraph's
  5724. world space parameters; this is required since the software character drawing
  5725. routines internally use world space coordinates.  The next statement is a
  5726. call to fg_setworld that establishes a world space coordinate system with
  5727. 0.01 world space units per pixel.  Following this is a call to fg_setsizew
  5728. that defines the character height as 0.21 world space units, or 21 pixels.
  5729. Note we could have instead used the fg_setsize routine here with an integer
  5730. argument of 21.
  5731.  
  5732.      The next part of the program draws the characters in the primary font on
  5733. the upper half of the screen.  After doing this, the program draws the
  5734. alternate font characters on the lower half.  In each case it does this with
  5735. the fg_swchar routine.  By default, the string passed to fg_swchar will
  5736. produce characters from the primary font.  However, you can insert a back
  5737. slash character (\) in the string to toggle between the two fonts.  Don't
  5738. forget the C language applies a special meaning to the back slash character
  5739. within strings, so you must use two consecutive back slashes to insert a
  5740. single back slash in the string.
  5741.  
  5742.                                  Example 7-8.
  5743.  
  5744.             #include <fastgraf.h>
  5745.             void main(void);
  5746.  
  5747.             void main()
  5748.             {
  5749.  
  5750. 110  Fastgraph User's Guide
  5751.  
  5752.                int old_mode;
  5753.  
  5754.                old_mode = fg_getmode();
  5755.                fg_setmode(16);
  5756.                fg_initw();
  5757.                fg_setworld(0.0,6.39,0.0,3.49);
  5758.                fg_setsizew(0.21);
  5759.  
  5760.                fg_setcolor(15);
  5761.                fg_locate(0,26);
  5762.                fg_text("Software characters - font 1",28);
  5763.                fg_setcolor(10);
  5764.                fg_movew(0.0,3.1);
  5765.                fg_swchar("ABCDEFGHIJKLMNOPQRSTUVWXYZ",26,-1);
  5766.                fg_movew(0.0,2.8);
  5767.                fg_swchar("abcdefghijklmnopqrstuvwxyz",26,-1);
  5768.                fg_movew(0.0,2.5);
  5769.                fg_swchar("0123456789",10,-1);
  5770.                fg_movew(0.0,2.2);
  5771.                fg_swchar("!\"#$%&'()*+,-./:;<=>?[]^`{|}~",29,-1);
  5772.  
  5773.                fg_setcolor(15);
  5774.                fg_locate(12,26);
  5775.                fg_text("Software characters - font 2",28);
  5776.                fg_setcolor(10);
  5777.                fg_movew(0.0,1.4);
  5778.                fg_swchar("\\ABCDEFGHIJKLMNOPRSTUWXYZ",25,-1);
  5779.                fg_movew(0.0,1.1);
  5780.                fg_swchar("\\abcdefghijklmnoprstuwxyz",25,-1);
  5781.                fg_movew(0.0,0.4);
  5782.                fg_swchar("\\012345678#$%&()*+/<=>?[]{}",27,-1);
  5783.                fg_waitkey();
  5784.  
  5785.                fg_setmode(old_mode);
  5786.                fg_reset();
  5787.             }
  5788.  
  5789.      Example 7-8 displays all characters in each font.  If you compare the
  5790. primary font strings with the alternate font strings, you'll see the
  5791. alternate font contains fewer characters.  For example, the letters Q and V
  5792. (either upper or lower case) have no corresponding character in the alternate
  5793. font.  You might have also noticed the primary font does not support the full
  5794. printable ASCII character set.  Any character in a string passed to the
  5795. fg_swchar routine that does not have a corresponding character in the current
  5796. font will display a blank character.
  5797.  
  5798.      In addition to the font change operator (the back slash character),
  5799. fg_swchar recognizes three other operators.  The superscript operator is a
  5800. back slash followed by a caret (\^).  It causes the next character to appear
  5801. as a superscript.  Similarly, the subscript operator is a back slash followed
  5802. by a lower case v (\v); it causes the next character to appear as a
  5803. subscript.  The size of superscripted and subscripted characters is one half
  5804. the height of the other characters.  The underline operator is the underscore
  5805. character (_).  It causes all subsequent characters in the string to be
  5806. underlined until another underscore character is found, or until the end of
  5807. the string.  When using these operators, be sure to include them as part of
  5808. the string length count passed to fg_swchar.
  5809.                                    Chapter 7:  Character Display Routines  111
  5810.  
  5811.      Example 7-9 illustrates the use of the font selection, superscript,
  5812. subscript, and underline operators with the fg_swchar routine.  Again,
  5813. because the back slash character has a special meaning to the C programming
  5814. language, we must use two consecutive back slashes to represent a single back
  5815. slash within the string.  The program displays four strings:
  5816.  
  5817.                               cos2o + sin2o = 1
  5818.                                      H2O
  5819.                                      U232
  5820.                            One word is underlined.
  5821.  
  5822. The theta symbol (o) in the first string is produced by displaying the
  5823. character "h" in the alternate font.  Note another font selection operator
  5824. (\) appears immediately after the "h" to revert to the primary font.  The
  5825. first string also includes superscript operators (\^) to display the
  5826. exponents in the equation.  The second string includes a single subscripted
  5827. character, while the third string shows how to display three consecutive
  5828. subscripted characters.  Finally, the fourth string illustrates how to
  5829. underline characters.
  5830.  
  5831.      Note example 7-9 also uses the fg_setratio routine.  The first three
  5832. strings are drawn with an aspect ratio of 2, making them twice as wide as
  5833. they are high.  The fourth string is drawn with an aspect ratio of 1
  5834. (Fastgraph's default aspect ratio for software characters), so the character
  5835. height is the same as the character width.  Also, the strings are centered
  5836. instead of left justified as in the previous example.
  5837.  
  5838.                                  Example 7-9.
  5839.  
  5840.             #include <fastgraf.h>
  5841.             void main(void);
  5842.  
  5843.             void main()
  5844.             {
  5845.                int old_mode;
  5846.  
  5847.                old_mode = fg_getmode();
  5848.                fg_setmode(16);
  5849.                fg_setcolor(10);
  5850.                fg_initw();
  5851.                fg_setworld(0.0,6.39,0.0,3.49);
  5852.                fg_setratio(2.0);
  5853.                fg_setsizew(0.21);
  5854.  
  5855.                fg_movew(3.2,3.0);
  5856.                fg_swchar("cos\\^2\\h\\ + sin\\^2\\h\\ = 1",25,0);
  5857.  
  5858.                fg_movew(3.2,2.0);
  5859.                fg_swchar("H\\v2O   U\\v2\\v3\\v2",18,0);
  5860.  
  5861.                fg_movew(3.2,1.0);
  5862.                fg_setratio(1.0);
  5863.                fg_swchar("One _word_ is underlined.",25,0);
  5864.                fg_waitkey();
  5865.  
  5866. 112  Fastgraph User's Guide
  5867.  
  5868.                fg_setmode(old_mode);
  5869.                fg_reset();
  5870.             }
  5871.  
  5872.      The fg_setangle routine defines the angle or orientation at which
  5873. software characters are displayed.  Its only argument is a floating point
  5874. value that specifies the angle, measured in degrees counterclockwise from the
  5875. positive x axis.  If a program draws software characters before calling
  5876. fg_setangle, Fastgraph will use its default angle of zero degrees (that is,
  5877. the characters will be oriented horizontally).
  5878.  
  5879.      In most programs, the alternate font is not needed.  However, if you use
  5880. the fg_swchar routine, Fastgraph will include the definitions of these
  5881. characters in your program's data segment.  To prevent wasting this space,
  5882. Fastgraph includes the fg_swtext routine.  The fg_swtext routine is same as
  5883. the fg_swchar routine, except it does not include the alternate font.  Since
  5884. the font selection operator does not apply when using fg_swtext, the routine
  5885. simply ignores it.  You should only use fg_swtext if do not use fg_swchar.
  5886. If you use both routines, your program will still work correctly, but its
  5887. data segment will contain an extra copy of the primary font definitions.
  5888.  
  5889.      Example 7-10 demonstrates the use of the fg_setangle and fg_swtext
  5890. routines.  The program draws a series of strings of the form "nnn degrees",
  5891. where nnn is a multiple of 15, radiating from the screen center.  Each string
  5892. appears at the specified angle.  For example, the string "15 degrees" is
  5893. drawn at an angle of 15 degrees.
  5894.  
  5895.                                 Example 7-10.
  5896.  
  5897.                #include <fastgraf.h>
  5898.                void main(void);
  5899.  
  5900.                void main()
  5901.                {
  5902.                   char string[24];
  5903.                   int angle;
  5904.                   int old_mode;
  5905.  
  5906.                   old_mode = fg_getmode();
  5907.                   fg_setmode(16);
  5908.                   fg_setcolor(10);
  5909.                   fg_initw();
  5910.                   fg_setworld(0.0,6.39,0.0,3.49);
  5911.                   fg_setsizew(0.21);
  5912.  
  5913.                   for (angle = 0; angle < 360; angle += 15) {
  5914.                      fg_movew(3.2,1.75);
  5915.                      fg_setangle((double)angle);
  5916.                      sprintf(string,"     %3d degrees",angle);
  5917.                      fg_swtext(string,16,-1);
  5918.                      }
  5919.                   fg_waitkey();
  5920.  
  5921.                   fg_setmode(old_mode);
  5922.                   fg_reset();
  5923.                }
  5924.  
  5925.                                    Chapter 7:  Character Display Routines  113
  5926.  
  5927.      The final routine pertaining to software characters is fg_swlength,
  5928. which returns the length of a specified string of software characters in
  5929. world space units.  The length is returned as the routine's floating point
  5930. function value.  The fg_swlength routine has two arguments -- a string of
  5931. software characters, and an integer value specifying the number of characters
  5932. in the string.  As with fg_swchar and fg_swtext, the count includes any of
  5933. the special operator characters.
  5934.  
  5935.      Example 7-11 demonstrates a typical use of the fg_swlength routine.  The
  5936. program displays the string "hello there." in light green against a gray
  5937. background in the middle of the screen.  As in our previous software
  5938. character examples, the program uses mode 16 and first performs the necessary
  5939. initializations to use software characters.  Following this, the program uses
  5940. the fg_swlength routine to compute the length in world space units of the
  5941. string.  Note we have added blank characters to each end of the string passed
  5942. to fg_swlength; this increases the length of the actual string and will
  5943. effectively give the gray rectangle an extended border on its left and right
  5944. sides.  The string length returned by fg_swlength is multiplied by 0.5,
  5945. giving the distance from the middle of the screen to either side of the
  5946. rectangle.  The program then uses this value to compute the minimum and
  5947. maximum x coordinates passed to fg_rectw.  After drawing the gray rectangle,
  5948. the program uses fg_swtext to draw the string of software characters in the
  5949. middle of the screen.  It then waits for a keystroke before restoring the
  5950. original video mode and screen attributes and returning to DOS.
  5951.  
  5952.                                 Example 7-11.
  5953.  
  5954.               #include <fastgraf.h>
  5955.               void main(void);
  5956.  
  5957.               void main()
  5958.               {
  5959.                  int old_mode;
  5960.                  double half;
  5961.                  double fg_swlength();
  5962.  
  5963.                  old_mode = fg_getmode();
  5964.                  fg_setmode(16);
  5965.                  fg_initw();
  5966.                  fg_setworld(0.0,6.39,0.0,3.49);
  5967.                  fg_setsizew(0.21);
  5968.  
  5969.                  fg_setcolor(7);
  5970.                  half = fg_swlength(" Hello there. ",14) * 0.5;
  5971.                  fg_rectw(3.2-half,3.2+half,1.6,1.9);
  5972.  
  5973.                  fg_setcolor(10);
  5974.                  fg_movew(3.2,1.65);
  5975.                  fg_swtext("Hello there.",12,0);
  5976.                  fg_waitkey();
  5977.  
  5978.                  fg_setmode(old_mode);
  5979.                  fg_reset();
  5980.               }
  5981.  
  5982. 114  Fastgraph User's Guide
  5983.  
  5984.  
  5985. Bit-Mapped Characters
  5986.  
  5987.      Bit-mapped characters combine the properties of hardware and software
  5988. characters.  They are a fixed size, as hardware characters are, but they can
  5989. be positioned anywhere instead of just in character cells.  Because they are
  5990. not scalable, they do not require floating point arithmetic, and therefore
  5991. they are much faster to display than software characters.
  5992.  
  5993.      Fastgraph makes no special provision for bit-mapped characters because
  5994. it treats them as if they were any other bit-mapped image.  For example, to
  5995. use a five-pixel by five-pixel bit-mapped font, you can construct characters
  5996. as shown below and then store these representations in an image array.
  5997.  
  5998.                           *       * * * *       * * * *
  5999.                         *   *     *       *   *
  6000.                       * * * * *   * * * *     *
  6001.                       *       *   *       *   *
  6002.                       *       *   * * * *       * * * *
  6003.  
  6004. The image display routines fg_drawmap and fg_drwimage, discussed in Chapter
  6005. 9, could then be used to display specific characters from the image array.
  6006.  
  6007.  
  6008. Summary of Character Display Routines
  6009.  
  6010.      This section summarizes the functional descriptions of the Fastgraph
  6011. routines presented in this chapter.  More detailed information about these
  6012. routines, including their arguments and return values, may be found in the
  6013. Fastgraph Reference Manual.
  6014.  
  6015.      FG_CHGATTR applies the current text display attribute to a given number
  6016. of characters, starting at the text cursor position.  This routine leaves the
  6017. text cursor one column to the right of the last character changed (or the
  6018. first column of the next row if the last character is at the end of a row).
  6019. It has no effect in graphics video modes.
  6020.  
  6021.      FG_CHGTEXT displays a string of hardware characters, starting at the
  6022. text cursor position, using the existing text display attributes.  This
  6023. routine leaves the text cursor one column to the right of the last character
  6024. displayed (or the first column of the next row if the last character is at
  6025. the end of a row).  It has no effect in graphics video modes.
  6026.  
  6027.      FG_GETATTR returns the character attribute stored at the specified
  6028. position on the active video page.  It has no effect in graphics video modes.
  6029.  
  6030.      FG_GETCHAR returns the character value stored at the specified position
  6031. on the active video page.  It has no effect in graphics video modes.
  6032.  
  6033.      FG_LOCATE changes the text cursor position for the active video page.
  6034.  
  6035.      FG_SETANGLE defines the angle or orientation at which software
  6036. characters are displayed.  The angle is measured in degrees counterclockwise
  6037. from the positive x axis.
  6038.  
  6039.      FG_SETATTR establishes the current text display attribute in text video
  6040. modes.  This routine has no effect in graphics video modes.
  6041.                                    Chapter 7:  Character Display Routines  115
  6042.  
  6043.      FG_SETCOLOR establishes the current color index (which may be a virtual
  6044. color index in graphics modes).  In text modes, the fg_setcolor routine
  6045. provides an alternate method of establishing the current text display
  6046. attribute.
  6047.  
  6048.      FG_SETRATIO defines the aspect ratio for software characters.  The
  6049. aspect ratio is the ratio of character width to character height.
  6050.  
  6051.      FG_SETSIZE defines the height of software characters in screen space
  6052. units.
  6053.  
  6054.      FG_SETSIZEW defines the height of software characters in world space
  6055. units.
  6056.  
  6057.      FG_SWCHAR displays a string of software characters using the current
  6058. color index.  The string may be left justified, centered, or right justified
  6059. relative to the graphics cursor position.  The string passed to fg_swchar may
  6060. contain special operators that allow switching between fonts, underlining,
  6061. superscripting, or subscripting.  This routine has no effect in text video
  6062. modes.
  6063.  
  6064.      FG_SWLENGTH returns the length in world space units of a string of
  6065. software characters.
  6066.  
  6067.      FG_SWTEXT is a scaled down version of the fg_swchar routine.  It does
  6068. not include the alternate font character definitions and thus requires less
  6069. memory than fg_swchar.
  6070.  
  6071.      FG_TEXT displays a string of hardware characters, starting at the text
  6072. cursor position, using the current color attribute (for text modes) or color
  6073. index (for graphics modes).  This routine leaves the text cursor one column
  6074. to the right of the last character displayed (or the first column of the next
  6075. row if the last character is at the end of a row).
  6076.  
  6077.      FG_WHERE retrieves the row and column numbers of the text cursor
  6078. position.
  6079.  
  6080.      FG_XALPHA and FG_YALPHA convert screen space coordinates to character
  6081. space.
  6082.  
  6083.      FG_XCONVERT and FG_YCONVERT convert character space coordinates to
  6084. screen space.
  6085. 116  Fastgraph User's Guide
  6086.  
  6087.  
  6088. Chapter 8
  6089.  
  6090. Video Page Management
  6091. 118  Fastgraph User's Guide
  6092.  
  6093.  
  6094. Overview
  6095.  
  6096.      The amount of memory required to store one full screen of information is
  6097. called a video page.  This chapter will discuss video pages in detail, along
  6098. with the Fastgraph routines you can use to manage video pages.
  6099.  
  6100.  
  6101. Physical Pages and Virtual Pages
  6102.  
  6103.      Pages that use the memory that resides on the video adapter are called
  6104. physical pages or true pages.  The number of physical pages available depends
  6105. on the video mode and the amount of memory resident on the user's video
  6106. adapter.  All video modes have at least one physical page.
  6107.  
  6108.      In certain video modes, Fastgraph can allocate available random-access
  6109. memory (RAM) and treat this memory as a video page.  Pages that use standard
  6110. RAM in this sense are called virtual pages.  From a programmer's perspective,
  6111. virtual pages are essentially identical to physical pages.
  6112.  
  6113.      The following table shows the number of physical pages in each video
  6114. mode.  It also indicates whether or not specific video modes support virtual
  6115. pages.
  6116.  
  6117.         Mode                              Page Size  Physical  Virtual
  6118.        Number Description                 in Bytes   Pages     Pages
  6119.  
  6120.          0    40 column color text          2,000    8         no
  6121.          1    40 column color text          2,000    8         no
  6122.          2    80 column color text          4,000    4         no
  6123.          3    80 column color text          4,000    4         no
  6124.          4    320 x 200 CGA graphics       16,000    1         yes
  6125.          5    320 x 200 CGA graphics       16,000    1         yes
  6126.          6    640 x 200 CGA graphics       16,000    1         yes
  6127.          7    80 column monochrome text     4,000    1         yes
  6128.          9    320 x 200 Tandy graphics     32,000    1         yes
  6129.          11   720 x 348 Hercules graphics  31,320    2         yes
  6130.          12   320 x 200 Hercules graphics  31,320    2         yes
  6131.          13   320 x 200 EGA graphics       32,000    8         no
  6132.          14   640 x 200 EGA graphics       64,000    4         no
  6133.          15   640 x 350 EGA mono graphics  56,000    2         no
  6134.          16   640 x 350 EGA graphics      112,000    2         no
  6135.          17   640 x 480 MCGA/VGA graphics  38,400    1+        no
  6136.          18   640 x 480 VGA graphics      153,600    1+        no
  6137.          19   320 x 200 MCGA graphics      64,000    1         yes
  6138.          20   320 x 200 VGA graphics       64,000    4         no
  6139.          21   320 x 400 VGA graphics      128,000    2         no
  6140.          22   320 x 240 VGA graphics       76,800    3+        no
  6141.          23   320 x 480 VGA graphics      153,600    1+        no
  6142.  
  6143. The preceding table assumes the video adapter for EGA and VGA modes contains
  6144. 256K bytes of video memory.  For EGA adapters with less video memory, the
  6145. number of physical pages is reduced proportionately.  In other words, a 64K
  6146. EGA has two video pages available instead of eight pages in mode 13.
  6147.                                         Chapter 8:  Video Page Management  119
  6148.  
  6149.      Note that the number of physical pages in some video modes is followed
  6150. by a plus symbol.  In these modes, there is an additional partial video page
  6151. available.  For modes 17, 18, and 23, there is one full page (page 0) plus
  6152. one partial page of 320 pixel rows (page 1).  For mode 22, there are three
  6153. full physical pages (numbered 0 to 2) plus one partial page of 80 pixel rows
  6154. (page 3).  You can safely use the partial pages as long as you don't
  6155. reference pixel rows beyond the last available row.  However, you cannot use
  6156. the fg_setvpage or the fg_text routines on the partial video page.
  6157.  
  6158.      Physical pages are numbered starting at zero.  For example, there are
  6159. four physical video pages available in mode 3, and they are numbered 0 to 3.
  6160. Virtual pages are numbered n to 63, where n is the number of physical pages
  6161. in that mode.  For example, there are two physical pages (numbered 0 and 1)
  6162. and 62 virtual pages (numbered 2 to 63) in mode 11.  Note only modes 4
  6163. through 12 and mode 19 offer virtual pages, and the amount of conventional
  6164. memory in the user's system usually limits the number of virtual pages
  6165. available (this is especially true in mode 19 because of the large page
  6166. size).
  6167.  
  6168.  
  6169. Pages With Special Meanings
  6170.  
  6171.      There are three video pages that have special meanings to Fastgraph.
  6172. The visual page, as one might guess, is the video page currently visible on
  6173. the user's display.  The active page is the video page to which Fastgraph
  6174. writes text or graphics information.  The hidden page is meaningful only to a
  6175. few Fastgraph routines and will be discussed specifically within the context
  6176. of those routines.  The fg_setmode routine sets all three of these pages to
  6177. page 0, and it does not matter if these pages are physical or virtual.
  6178.  
  6179.      One of the most useful features of multiple video pages (either physical
  6180. or virtual) is the ability to build a text or graphics image off screen (that
  6181. is, on some video page besides the visual page).  Then, once the image is
  6182. ready, we can either transfer it to the visual page, or make the page on
  6183. which the image resides the visual page.  This feature is especially useful
  6184. in animation, for it displays an image instantaneously instead of visibly
  6185. updating the screen while producing the image.
  6186.  
  6187.  
  6188. Some Simple Examples
  6189.  
  6190.      In this section, we will present six variations of a simple program that
  6191. uses four video pages.  The program fills each video page with a rectangle
  6192. and then displays text containing the video page number in the center of each
  6193. page.  The first two examples run in a specific text or graphics video mode
  6194. and only use physical pages.  The next two examples also run in a specific
  6195. text or graphics video mode, but they also use virtual pages.  The final two
  6196. examples are more general and run in several video modes.  You could of
  6197. course write a program that essentially does the same thing as the examples
  6198. in this section without using multiple video pages.  However, to use
  6199. Fastgraph's image display and animation routines effectively, you must first
  6200. understand the concept of video pages.
  6201.  
  6202.      Before proceeding, we must introduce the Fastgraph routines fg_setpage
  6203. and fg_setvpage.  The fg_setpage routine defines the active video page, which
  6204. causes Fastgraph to put subsequent text and graphics output on that page.
  6205. The fg_setvpage routine defines the visual video page displayed on the
  6206. 120  Fastgraph User's Guide
  6207.  
  6208. screen.  Both routines take a single integer argument between 0 and 63 that
  6209. specifies the video page number.  It does not matter if the referenced video
  6210. page is a physical page or a virtual page.  As mentioned earlier, fg_setmode
  6211. makes page 0 the active and visual video page.
  6212.  
  6213.      Example 8-1 uses four video pages (numbered 0 to 3) in the 40-column
  6214. color text mode (mode 1).  The program first calls fg_testmode to check the
  6215. availability of the requested video mode when used with four video pages.  If
  6216. it is available, the program calls fg_setmode to establish that video mode.
  6217. The first for loop fills each of the four pages with different color
  6218. rectangles and then displays black text containing the video page number in
  6219. the center of each page.  It does this by calling fg_setpage to define the
  6220. active video page, fg_setcolor and fg_rect to draw the colored rectangles,
  6221. and finally fg_setattr, fg_locate, and fg_text to display the text.  The
  6222. program must call fg_locate inside the loop because each video page has its
  6223. own text cursor position.  The second for loop successively makes each video
  6224. page the visual page; the page remains displayed until you press a key.
  6225. After displaying all four video pages, the program restores the original
  6226. video mode and screen attributes before returning to DOS.
  6227.  
  6228.                                  Example 8-1.
  6229.  
  6230.                #include <fastgraf.h>
  6231.                #include <stdio.h>
  6232.                #include <stdlib.h>
  6233.                void main(void);
  6234.  
  6235.                #define PAGES 4
  6236.  
  6237.                void main()
  6238.                {
  6239.                   int color;
  6240.                   int old_mode;
  6241.                   int page;
  6242.                   char string[8];
  6243.  
  6244.                   if (fg_testmode(1,PAGES) == 0) {
  6245.                      printf("This program requires color.\n");
  6246.                      exit(1);
  6247.                      }
  6248.  
  6249.                   old_mode = fg_getmode();
  6250.                   fg_setmode(1);
  6251.  
  6252.                   for (page = 0; page < PAGES; page++) {
  6253.                      fg_setpage(page);
  6254.                      color = page + 1;
  6255.                      fg_setcolor(color);
  6256.                      fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  6257.                      fg_setattr(0,color,0);
  6258.                      fg_locate(12,17);
  6259.                      sprintf(string,"page %d",page);
  6260.                      fg_text(string,6);
  6261.                      }
  6262.  
  6263.                   for (page = 0; page < PAGES; page++) {
  6264.  
  6265.                                         Chapter 8:  Video Page Management  121
  6266.  
  6267.                      fg_setvpage(page);
  6268.                      fg_waitkey();
  6269.                      }
  6270.                   fg_setmode(old_mode);
  6271.                   fg_reset();
  6272.                }
  6273.  
  6274.      Example 8-2 is similar to example 8-1, but it uses the 320 by 200 EGA
  6275. graphics mode (mode 13) instead of a text mode.  Note the only real
  6276. difference between this program and the text mode version is the use of
  6277. fg_setcolor instead of fg_setattr to make the text appear in black.
  6278.  
  6279.                                  Example 8-2.
  6280.  
  6281.                #include <fastgraf.h>
  6282.                #include <stdio.h>
  6283.                #include <stdlib.h>
  6284.                void main(void);
  6285.  
  6286.                #define PAGES 4
  6287.  
  6288.                void main()
  6289.                {
  6290.                   int color;
  6291.                   int old_mode;
  6292.                   int page;
  6293.                   char string[8];
  6294.  
  6295.                   if (fg_testmode(13,PAGES) == 0) {
  6296.                      printf("This program requires a ");
  6297.                      printf("320 x 200 EGA graphics mode.\n");
  6298.                      exit(1);
  6299.                      }
  6300.  
  6301.                   old_mode = fg_getmode();
  6302.                   fg_setmode(13);
  6303.  
  6304.                   for (page = 0; page < PAGES; page++) {
  6305.                      fg_setpage(page);
  6306.                      color = page + 1;
  6307.                      fg_setcolor(color);
  6308.                      fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  6309.                      fg_setcolor(0);
  6310.                      fg_locate(12,17);
  6311.                      sprintf(string,"page %d",page);
  6312.                      fg_text(string,6);
  6313.                      }
  6314.  
  6315.                   for (page = 0; page < PAGES; page++) {
  6316.                      fg_setvpage(page);
  6317.                      fg_waitkey();
  6318.                      }
  6319.  
  6320.                   fg_setmode(old_mode);
  6321.                   fg_reset();
  6322.                }
  6323.  
  6324. 122  Fastgraph User's Guide
  6325.  
  6326.      Virtual video pages are created with Fastgraph's fg_allocate routine.
  6327. The fg_allocate routine reserves conventional random-access memory (RAM)
  6328. which Fastgraph then treats as a video page.  The amount of memory required
  6329. depends on the current video mode.  The fg_allocate routine takes a single
  6330. integer argument that specifies the page number by which the virtual page
  6331. will be referenced.  This value must be between 0 and 63.
  6332.  
  6333.      If you try to create a virtual page with a page number already assigned
  6334. to a physical page, fg_allocate does nothing.  For example, in the Hercules
  6335. graphics modes (modes 11 and 12) there are two physical pages numbered 0 and
  6336. 1.  Virtual pages in the Hercules graphics modes must thus have page numbers
  6337. between 2 and 63.  If you tell fg_allocate to create a Hercules virtual page
  6338. numbered 0 or 1, it does nothing because those video pages are physical
  6339. pages.  Similarly, if you use the fg_allocate routine in a video mode that
  6340. does not support virtual video pages, it simply returns without doing
  6341. anything.
  6342.  
  6343.      A possible problem with fg_allocate can occur when there is not enough
  6344. memory available for creating a virtual page in the current video mode.  The
  6345. fg_allocate routine returns as its function value a status code indicating
  6346. whether or not it was successful.  The possible values of the status code
  6347. are:
  6348.  
  6349.     value  meaning
  6350.  
  6351.       0    virtual page created
  6352.       1    specified page number is a physical page
  6353.       7   virtual page created, but memory control blocks were destroyed
  6354.       8   insufficient memory to create the virtual page
  6355.  
  6356. If you use the fg_testmode or fg_bestmode routines to check if the required
  6357. number of video pages are available when using the requested video mode, you
  6358. should not need to monitor the status code returned by the fg_allocate
  6359. routine.
  6360.  
  6361.      The fg_freepage routine releases the memory for a virtual page created
  6362. with the fg_allocate routine.  It requires a single integer argument that
  6363. specifies the virtual page number to release.  This value must be between 0
  6364. and 63.  If you try to release a physical video page, or release a virtual
  6365. page that was never created, fg_freepage does nothing.  It is a good idea to
  6366. use fg_freepage to release all virtual video pages before a program returns
  6367. control to DOS, or just before a program selects a new video mode.
  6368.  
  6369.      Example 8-3 is also similar to example 8-1, but it uses the monochrome
  6370. text mode (mode 7).  Because the monochrome text mode only has one physical
  6371. video page, we must use virtual video pages for page numbers 1, 2, and 3.
  6372. Note how the fg_allocate and fg_freepage routines are used to create and
  6373. release the virtual video pages in this example.
  6374.  
  6375.                                  Example 8-3.
  6376.  
  6377.              #include <fastgraf.h>
  6378.              #include <stdio.h>
  6379.  
  6380.                                         Chapter 8:  Video Page Management  123
  6381.  
  6382.              #include <stdlib.h>
  6383.              void main(void);
  6384.  
  6385.              #define PAGES 4
  6386.  
  6387.              void main()
  6388.              {
  6389.                 int old_mode;
  6390.                 int page;
  6391.                 char string[8];
  6392.  
  6393.                 if (fg_testmode(7,PAGES) == 0) {
  6394.                    printf("This program requires monochrome.\n");
  6395.                    exit(1);
  6396.                    }
  6397.  
  6398.                 old_mode = fg_getmode();
  6399.                 fg_setmode(7);
  6400.                 fg_cursor(0);
  6401.  
  6402.                 for (page = 0; page < PAGES; page++) {
  6403.                    fg_allocate(page);
  6404.                    fg_setpage(page);
  6405.                    fg_setcolor(7);
  6406.                    fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  6407.                    fg_setattr(0,7,0);
  6408.                    fg_locate(12,37);
  6409.                    sprintf(string,"page %d",page);
  6410.                    fg_text(string,6);
  6411.                    }
  6412.  
  6413.                 for (page = 0; page < PAGES; page++) {
  6414.                    fg_setvpage(page);
  6415.                    fg_waitkey();
  6416.                    fg_freepage(page);
  6417.                    }
  6418.  
  6419.                 fg_setmode(old_mode);
  6420.                 fg_reset();
  6421.              }
  6422.  
  6423.      Example 8-4 is similar to example 8-3, but it uses the standard Hercules
  6424. graphics mode (mode 11) instead of the monochrome text mode.  Because the
  6425. Hercules graphics modes have two physical video pages, we must use virtual
  6426. video pages for page numbers 2 and 3.  Note the only real difference between
  6427. this program and the text mode version is the use of fg_setcolor instead of
  6428. fg_setattr to make the text appear in black.
  6429.  
  6430.                                  Example 8-4.
  6431.  
  6432.                #include <fastgraf.h>
  6433.                #include <stdio.h>
  6434.                #include <stdlib.h>
  6435.                void main(void);
  6436.  
  6437.                #define PAGES 4
  6438.  
  6439. 124  Fastgraph User's Guide
  6440.  
  6441.                void main()
  6442.                {
  6443.                   int old_mode;
  6444.                   int page;
  6445.                   char string[8];
  6446.  
  6447.                   if (fg_testmode(11,PAGES) == 0) {
  6448.                      printf("This program requires Hercules ");
  6449.                      printf("monochrome graphics.\n");
  6450.                      exit(1);
  6451.                      }
  6452.  
  6453.                   old_mode = fg_getmode();
  6454.                   fg_setmode(11);
  6455.  
  6456.                   for (page = 0; page < PAGES; page++) {
  6457.                      fg_allocate(page);
  6458.                      fg_setpage(page);
  6459.                      fg_setcolor(7);
  6460.                      fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  6461.                      fg_setcolor(0);
  6462.                      fg_locate(12,37);
  6463.                      sprintf(string,"page %d",page);
  6464.                      fg_text(string,6);
  6465.                      }
  6466.  
  6467.                   for (page = 0; page < PAGES; page++) {
  6468.                      fg_setvpage(page);
  6469.                      fg_waitkey();
  6470.                      fg_freepage(page);
  6471.                      }
  6472.  
  6473.                   fg_setmode(old_mode);
  6474.                   fg_reset();
  6475.                }
  6476.  
  6477.      Example 8-5 is a generalized version of examples 8-1 and 8-3 that runs
  6478. in any 80-column text video mode.  To simplify the program, each video page
  6479. is filled with rectangles of the same color.  Note that fg_allocate and
  6480. fg_freepage are used to manage the virtual video pages in case fg_bestmode
  6481. selects the monochrome text mode (mode 7).  If fg_bestmode selects one of the
  6482. 80-column color text modes (which have four physical video pages),
  6483. fg_allocate and fg_freepage will simply return without doing anything.
  6484.  
  6485.                                  Example 8-5.
  6486.  
  6487.                 #include <fastgraf.h>
  6488.                 #include <stdio.h>
  6489.                 #include <stdlib.h>
  6490.                 void main(void);
  6491.  
  6492.                 #define PAGES 4
  6493.  
  6494.                 void main()
  6495.                 {
  6496.                    int old_mode, new_mode;
  6497.  
  6498.                                         Chapter 8:  Video Page Management  125
  6499.                    int page;
  6500.                    char string[8];
  6501.  
  6502.                    new_mode = fg_bestmode(80,25,PAGES);
  6503.                    if (new_mode < 0) {
  6504.                       printf("This program requires ");
  6505.                       printf("an 80-column display.\n");
  6506.                       exit(1);
  6507.                       }
  6508.                    old_mode = fg_getmode();
  6509.                    fg_setmode(new_mode);
  6510.                    fg_cursor(0);
  6511.  
  6512.                    for (page = 0; page < PAGES; page++) {
  6513.                       fg_allocate(page);
  6514.                       fg_setpage(page);
  6515.                       fg_setcolor(7);
  6516.                       fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  6517.                       fg_setattr(0,7,0);
  6518.                       fg_locate(12,37);
  6519.                       sprintf(string,"page %d",page);
  6520.                       fg_text(string,6);
  6521.                       }
  6522.  
  6523.                    for (page = 0; page < PAGES; page++) {
  6524.                       fg_setvpage(page);
  6525.                       fg_waitkey();
  6526.                       fg_freepage(page);
  6527.                       }
  6528.  
  6529.                    fg_setmode(old_mode);
  6530.                    fg_reset();
  6531.                 }
  6532.  
  6533.      Example 8-6 is a generalized version of examples 8-2 and 8-4 that runs
  6534. in any 320 by 200 graphics video mode.  To simplify the program, each video
  6535. page is filled with rectangles of the same color.  As in example 8-5,
  6536. fg_allocate and fg_freepage are used to manage the virtual video pages in
  6537. case fg_bestmode selects a video mode with fewer than four physical video
  6538. pages.  Note the only real difference between this program and the text mode
  6539. version is the use of fg_setcolor instead of fg_setattr to make the text
  6540. appear in black.
  6541.  
  6542.                                  Example 8-6.
  6543.  
  6544.                 #include <fastgraf.h>
  6545.                 #include <stdio.h>
  6546.                 #include <stdlib.h>
  6547.                 void main(void);
  6548.  
  6549.                 #define PAGES 4
  6550.  
  6551.                 void main()
  6552.                 {
  6553.                    int old_mode, new_mode;
  6554.                    int page;
  6555.                    char string[8];
  6556.  
  6557. 126  Fastgraph User's Guide
  6558.  
  6559.  
  6560.                    new_mode = fg_bestmode(320,200,PAGES);
  6561.                    if (new_mode < 0) {
  6562.                       printf("This program requires a ");
  6563.                       printf("320 x 200 graphics mode.\n");
  6564.                       exit(1);
  6565.                       }
  6566.  
  6567.                    old_mode = fg_getmode();
  6568.                    fg_setmode(new_mode);
  6569.  
  6570.                    for (page = 0; page < PAGES; page++) {
  6571.                       fg_allocate(page);
  6572.                       fg_setpage(page);
  6573.                       fg_setcolor(15);
  6574.                       fg_rect(0,fg_getmaxx(),0,fg_getmaxy());
  6575.                       fg_setcolor(0);
  6576.                       fg_locate(12,17);
  6577.                       sprintf(string,"page %d",page);
  6578.                       fg_text(string,6);
  6579.                       }
  6580.  
  6581.                    for (page = 0; page < PAGES; page++) {
  6582.                       fg_setvpage(page);
  6583.                       fg_waitkey();
  6584.                       fg_freepage(page);
  6585.                       }
  6586.  
  6587.                    fg_setmode(old_mode);
  6588.                    fg_reset();
  6589.                 }
  6590.  
  6591.  
  6592. Text Cursors
  6593.  
  6594.      As mentioned in the previous chapter, Fastgraph draws hardware
  6595. characters at the position defined by the text cursor.  Like the graphics
  6596. cursor, the text cursor is not a cursor in the true sense, but is simply a
  6597. pair of character space (row,column) coordinates with a special meaning.  The
  6598. first 8 video pages (that is, pages 0 through 7) each have their own text
  6599. cursor.  Each subsequent group of 8 video pages (pages 8 through 15, pages 16
  6600. to 23, and so forth) respectively share the same text cursor positions as the
  6601. first 8 pages.  This means the fg_locate routine will update one of 8
  6602. different text cursors depending on the active video page.  Similarly, the
  6603. fg_where routine returns the text cursor position for the active page.  The
  6604. fg_setmode routine sets all 8 text cursor positions to the character space
  6605. coordinates (0,0).
  6606.  
  6607.      Example 8-7 demonstrates the use of different text cursors in an 80-
  6608. column color text mode (mode 3).  The program first displays the text "Page "
  6609. on video page 0 (the visible page) and waits for a keystroke.  It then makes
  6610. page 1 the active video page, changes the text cursor location for that page,
  6611. and displays the text "Page 1" on video page 1.  Next, it appends the
  6612. character "0" to the text originally displayed on page 0.  Note it is not
  6613. necessary to restore the text cursor position for page 0 because it is
  6614. unaffected by changing the text cursor for page 1.  After waiting for another
  6615.                                         Chapter 8:  Video Page Management  127
  6616.  
  6617. keystroke, the program makes video page 1 the visual page and then waits for
  6618. yet another keystroke before returning to DOS.
  6619.  
  6620.                                  Example 8-7.
  6621.  
  6622.                          #include <fastgraf.h>
  6623.                          void main(void);
  6624.  
  6625.                          void main()
  6626.                          {
  6627.                             int old_mode;
  6628.  
  6629.                             old_mode = fg_getmode();
  6630.                             fg_setmode(3);
  6631.                             fg_cursor(0);
  6632.                             fg_setattr(10,0,0);
  6633.  
  6634.                             fg_locate(1,0);
  6635.                             fg_text("Page ",5);
  6636.                             fg_waitkey();
  6637.  
  6638.                             fg_setpage(1);
  6639.                             fg_locate(23,0);
  6640.                             fg_text("Page 1",6);
  6641.  
  6642.                             fg_setpage(0);
  6643.                             fg_text("0",1);
  6644.                             fg_waitkey();
  6645.  
  6646.                             fg_setvpage(1);
  6647.                             fg_waitkey();
  6648.  
  6649.                             fg_setmode(old_mode);
  6650.                             fg_reset();
  6651.                          }
  6652.  
  6653.  
  6654. Obtaining Video Page Information
  6655.  
  6656.      Fastgraph includes two routines, fg_getpage and fg_getvpage, that
  6657. respectively return the current active or visual video page number.  Each
  6658. routine returns the video page number as its function value, and neither
  6659. routine requires any arguments.
  6660.  
  6661.      The fg_getaddr routine is sometimes useful when using virtual pages.  It
  6662. returns as its function value the segment address for the start of the active
  6663. video page.  It does not require any arguments.  Although fg_getaddr is more
  6664. useful when using virtual video pages, it works equally well when using
  6665. physical video pages.
  6666.  
  6667.      Example 8-8 illustrates the use of the fg_getpage, fg_getvpage, and
  6668. fg_getaddr routines in the standard CGA color graphics mode (mode 4).  This
  6669. video mode offers only one physical page, so the program uses fg_allocate to
  6670. create a virtual video page (page 1).  After creating the virtual page, the
  6671. program makes it the active video page; page 0 remains the visual video page.
  6672. The fg_getpage routine then returns the active page number (1), followed by a
  6673. call to fg_getvpage to return the visual page number (0).  Next, the program
  6674. 128  Fastgraph User's Guide
  6675.  
  6676. uses fg_getaddr to return the segment address for video pages 0 and 1.
  6677. Finally, it restores the original video mode and screen attributes, displays
  6678. the returned values, and returns to DOS.
  6679.  
  6680.                                  Example 8-8.
  6681.  
  6682.                  #include <fastgraf.h>
  6683.                  #include <stdio.h>
  6684.                  void main(void);
  6685.  
  6686.                  void main()
  6687.                  {
  6688.                     int old_mode;
  6689.                     int active, visual;
  6690.                     int page0, page1;
  6691.  
  6692.                     old_mode = fg_getmode();
  6693.                     fg_setmode(4);
  6694.                     fg_allocate(1);
  6695.                     fg_setpage(1);
  6696.  
  6697.                     active = fg_getpage();
  6698.                     visual = fg_getvpage();
  6699.  
  6700.                     fg_setpage(0);
  6701.                     page0 = fg_getaddr();
  6702.                     fg_setpage(1);
  6703.                     page1 = fg_getaddr();
  6704.  
  6705.                     fg_freepage(1);
  6706.                     fg_setmode(old_mode);
  6707.                     fg_reset();
  6708.  
  6709.                     printf("Active page is %d.\n",active);
  6710.                     printf("Visual page is %d.\n",visual);
  6711.                     printf("Page 0 address is %4X\n",page0);
  6712.                     printf("Page 1 address is %4X\n",page1);
  6713.                  }
  6714.  
  6715.  
  6716. Considerations for Virtual Pages
  6717.  
  6718.      When you are using virtual pages, you should avoid using the fg_setvpage
  6719. routine in sections of the program that require fast screen updates or
  6720. animation sequences.  This is because the PC and PS/2 video BIOS are only
  6721. capable of displaying physical pages.  To compensate for this restriction,
  6722. Fastgraph exchanges the contents of a physical page with the requested
  6723. virtual page.  In other words, if page 1 is a virtual page and you make it
  6724. the visual page, Fastgraph will exchange the contents of page 1 with whatever
  6725. page was previously the visual page.  This does not mean Fastgraph's page
  6726. numbers change because Fastgraph also maintains an internal table containing
  6727. video page addresses and exchanges the two corresponding table entries.  As
  6728. before, you would make page 1 the active video page if you wanted to write
  6729. something to the visual page.
  6730.  
  6731.      About the only other potential problem when using virtual pages is what
  6732. happens when you try to write to a non-existent video page (for example, if
  6733.                                         Chapter 8:  Video Page Management  129
  6734.  
  6735. you write to virtual video page 1 before creating it with fg_allocate).  In
  6736. this case, Fastgraph simply redirects the video output to the visual page.
  6737.  
  6738.  
  6739. Logical Pages
  6740.  
  6741.      In addition to physical and virtual video pages, Fastgraph offers
  6742. another class of video pages, called logical pages.  You can create logical
  6743. pages in any video mode.  They can exist in conventional memory, expanded
  6744. memory (EMS), or extended memory (XMS).  However, they are not as versatile
  6745. as physical or virtual pages because the only operations you can perform with
  6746. logical pages are:
  6747.  
  6748.        Copy an entire physical or virtual page to a logical page
  6749.        Copy an entire logical page to a physical or virtual page
  6750.        Copy an entire logical page to another logical page
  6751.  
  6752. Three Fastgraph routines -- fg_alloccms, fg_allocems, and fg_allocxms --
  6753. create logical pages in conventional memory, expanded memory, and extended
  6754. memory, respectively.  All three routines have a single integer argument that
  6755. specifies the page number by which the logical page will be referenced.  The
  6756. page number must be between 1 and 63 and must not reference a physical or
  6757. virtual page.  Their return value is 0 if the logical page is created, and
  6758. negative otherwise (refer to the descriptions of these routines in the
  6759. Fastgraph Reference Manual for a complete list of return values).  As with
  6760. virtual pages, use the fg_freepage function to release a logical page.
  6761.  
  6762.      Before you can create logical pages in expanded or extended memory, you
  6763. must initialize these resources for use with Fastgraph.  The fg_initems
  6764. routine initializes expanded memory.  To use expanded memory, you must have
  6765. an Expanded Memory Manager (EMM) that conforms to the Lotus/Intel/Microsoft
  6766. Expanded Memory Specification (LIM-EMS) version 3.2 or later.  On 80386 and
  6767. 80486 systems, the EMM386.EXE device driver supplied with DOS 5.0 can be used
  6768. to treat some or all of extended memory as expanded memory.  The fg_initxms
  6769. routine initializes extended memory for use with Fastgraph.  To use extended
  6770. memory, you must have an XMS driver that conforms to the
  6771. Lotus/Intel/Microsoft/AST eXtended Memory Specification version 2.0 or later,
  6772. such as HIMEM.SYS.  XMS drivers require an 80286, 80386, or 80486 system.
  6773. The fg_initems and fg_initxms routines have no arguments.  Their return value
  6774. is 0 if successful, and -1 if the required driver and resources are not
  6775. present.
  6776.  
  6777.      Example 8-9 illustrates the use of logical pages in a 320 x 200 color
  6778. graphics mode.  The program first tries to create a logical page in extended
  6779. memory by calling fg_initxms and fg_allocxms.  If the initialization or page
  6780. creation fails, it then tries to create the page in expanded memory with
  6781. fg_initems and fg_allocems.  Should that fail, the program calls fg_alloccms
  6782. to try to create the page in conventional memory.  If it can't create the
  6783. logical page at all, the program displays an error message and exits.
  6784.  
  6785.      Once the logical page is created, example 8-9 displays the word "test"
  6786. in the middle of the visual page (page 0) and then uses fg_copypage to
  6787. transfer the visual page contents to the logical page (page 8).  Because this
  6788. program runs in one of several different graphics modes, we must use a
  6789. logical page number greater than any possible physical page number.  We chose
  6790. page 8 because mode 13 has physical pages numbered 0 through 7, and no mode
  6791. has higher-numbered physical pages.  After waiting for a keystroke, the
  6792. 130  Fastgraph User's Guide
  6793.  
  6794. program erases the visual page, waits for another keystroke, and copies the
  6795. logical page contents back to the visual page.  It then releases the logical
  6796. page and exits.
  6797.  
  6798.                                  Example 8-9.
  6799.  
  6800.               #include <fastgraf.h>
  6801.               #include <stdio.h>
  6802.               #include <stdlib.h>
  6803.               void main(void);
  6804.  
  6805.               void main()
  6806.               {
  6807.                  int new_mode, old_mode;
  6808.                  int status;
  6809.  
  6810.                  new_mode = fg_bestmode(320,200,1);
  6811.                  if (new_mode < 0 || new_mode == 12) {
  6812.                     printf("This program requires a 320 ");
  6813.                     printf("x 200 color graphics mode.\n");
  6814.                     exit(1);
  6815.                     }
  6816.                  old_mode = fg_getmode();
  6817.                  fg_setmode(new_mode);
  6818.  
  6819.                  status = fg_initxms();
  6820.                  if (status == 0) status = fg_allocxms(8);
  6821.                  if (status < 0) {
  6822.                     status = fg_initems();
  6823.                     if (status == 0) status = fg_allocems(8);
  6824.                     }
  6825.                  if (status < 0) status = fg_alloccms(8);
  6826.                  if (status < 0) {
  6827.                     fg_setmode(old_mode);
  6828.                     fg_reset();
  6829.                     printf("Unable to create logical page.\n");
  6830.                     exit(1);
  6831.                     }
  6832.  
  6833.                  fg_setcolor(7);
  6834.                  fg_rect(0,319,0,199);
  6835.                  fg_setcolor(9);
  6836.                  fg_locate(12,18);
  6837.                  fg_text("test",4);
  6838.                  fg_waitkey();
  6839.  
  6840.                  fg_copypage(0,8);
  6841.                  fg_erase();
  6842.                  fg_waitkey();
  6843.                  fg_copypage(8,0);
  6844.                  fg_waitkey();
  6845.  
  6846.                  fg_freepage(8);
  6847.                  fg_setmode(old_mode);
  6848.                  fg_reset();
  6849.               }
  6850.  
  6851.                                         Chapter 8:  Video Page Management  131
  6852.  
  6853.      As mentioned before, the only function you can perform with logical
  6854. pages is copying one video page to another.  The fg_copypage routine provides
  6855. the only way to do this for logical pages.  See page 175 for a description of
  6856. fg_copypage.
  6857.  
  6858.  
  6859. Video Page Resizing
  6860.  
  6861.      Resizing is the process of changing the dimensions of a video page.  It
  6862. is available only in the native EGA graphics modes (modes 13 to 16), native
  6863. VGA graphics modes (modes 17 and 18), and extended VGA modes (modes 20 to
  6864. 23).  Resizing does not change the screen resolution, but instead increases
  6865. the video page size so that only part of the page is visible.  For now, we'll
  6866. just introduce resizing with a simple example, but in Chapter 11 we'll see
  6867. its real power when we perform smooth panning.
  6868.  
  6869.      The Fastgraph routine fg_resize changes the dimensions of a video page.
  6870. Its two integer arguments define the page width and page height, both in
  6871. pixels.  Example 8-10 runs in the 320 x 200 EGA graphics mode (mode 13).
  6872. After establishing the video mode, it displays the word "resize" starting in
  6873. column 38 of row 0.  Because the characters extend beyond the last column of
  6874. the row, they wrap to the next row.  The program continues displaying this
  6875. until you press a key.  Then, it clears the screen and calls fg_resize to
  6876. make the page size 640 x 200 pixels.  Again the program displays the word
  6877. "resize" starting in column 38 of row 0, but this time it does not wrap to
  6878. the next row.  This is because the resizing doubled the page width, which
  6879. increased the number of character cells per row from 40 to 80.  The
  6880. characters that formerly wrapped to the next row now continue on an off-
  6881. screen portion of the same row.
  6882.  
  6883.                                 Example 8-10.
  6884.  
  6885.                 #include <fastgraf.h>
  6886.                 #include <stdio.h>
  6887.                 #include <stdlib.h>
  6888.                 void main(void);
  6889.  
  6890.                 void main()
  6891.                 {
  6892.                    int old_mode;
  6893.  
  6894.                    if (fg_testmode(13,1) == 0) {
  6895.                       printf("This program requires a 320 ");
  6896.                       printf("x 200 EGA graphics mode.\n");
  6897.                       exit(1);
  6898.                       }
  6899.  
  6900.                    old_mode = fg_getmode();
  6901.                    fg_setmode(13);
  6902.  
  6903.                    fg_setcolor(9);
  6904.                    fg_locate(0,38);
  6905.                    fg_text("resize",6);
  6906.                    fg_waitkey();
  6907.  
  6908.                    fg_erase();
  6909.  
  6910. 132  Fastgraph User's Guide
  6911.  
  6912.                    fg_resize(640,200);
  6913.                    fg_setcolor(10);
  6914.                    fg_locate(0,38);
  6915.                    fg_text("resize",6);
  6916.                    fg_waitkey();
  6917.  
  6918.                    fg_setmode(old_mode);
  6919.                    fg_reset();
  6920.                 }
  6921.  
  6922.      The size of a video page is constrained only by the amount of video
  6923. memory available.  Increasing the video page size reduces the number of
  6924. physical pages available proportionally.  In mode 13, for example, increasing
  6925. the page size from 320 x 200 to 640 x 400 reduces the number of video pages
  6926. from 8 to 2.  When you call fg_resize, the visual page must be page 0.  If
  6927. you have created any logical video pages, you must release them with
  6928. fg_freepage before calling fg_resize, and then create them again afterward.
  6929. If you have initialized the mouse (with fg_mouseini), joysticks (with
  6930. fg_initjoy), expanded memory (with fg_initems), or extended memory (with
  6931. fg_initxms), you should re-initialize these resources after calling
  6932. fg_resize.  Most mouse drivers expect a fixed video page width, so the mouse
  6933. cursor may become distorted after resizing video pages.  When you call
  6934. fg_resize, Fastgraph sets the clipping region to the new page limits.  The
  6935. fg_setmode routine re-establishes the dimensions of a video page to the
  6936. default screen resolution for the selected video mode.
  6937.  
  6938.       Depending on the dimensions passed to fg_resize, you may end up with a
  6939. partial video page.  Again, suppose we're using mode 13 and have changed the
  6940. page size to 960 x 400 (this is six times the default page size).  The
  6941. original pages 0 to 5 now comprise page 0, and original pages 6 and 7 now
  6942. comprise page 1.  However, there is not enough video memory left on page 1
  6943. for a full 960 x 400 page.  In this case, the number of pixel rows available
  6944. on page 1 would be one-third the full page size, or 133 rows.  This is
  6945. because the total storage required by original pages 6 and 7 is one-third the
  6946. total required for original pages 0 through 5.
  6947.  
  6948.  
  6949. Summary of Video Page Management Routines
  6950.  
  6951.      This section summarizes the functional descriptions of the Fastgraph
  6952. routines presented in this chapter.  More detailed information about these
  6953. routines, including their arguments and return values, may be found in the
  6954. Fastgraph Reference Manual.
  6955.  
  6956.      FG_ALLOCATE creates a virtual video page.  The amount of memory required
  6957. depends on the current video mode.  This routine has no effect if it
  6958. references a physical or logical video page.
  6959.  
  6960.      FG_ALLOCEMS creates a logical page in expanded memory (EMS).  The amount
  6961. of memory required depends on the current video mode and video buffer
  6962. dimensions.  This routine has no effect if it references a physical or
  6963. virtual video page.
  6964.  
  6965.      FG_ALLOCXMS creates a logical page in extended memory (XMS).  The amount
  6966. of memory required depends on the current video mode and video buffer
  6967. dimensions.  This routine has no effect if it references a physical or
  6968. virtual video page.
  6969.                                         Chapter 8:  Video Page Management  133
  6970.  
  6971.      FG_COPYPAGE transfers the contents of one video page to another.  The
  6972. pages may be physical, virtual, or logical video pages.  If both pages are
  6973. logical pages, they must exist in the same type of memory.
  6974.  
  6975.      FG_FREEPAGE releases a virtual or logical video page created with the
  6976. fg_allocate, fg_alloccms, fg_allocems, or fg_allocxms routines.  This routine
  6977. has no effect if it references a physical video page, or a virtual page that
  6978. was never created.
  6979.  
  6980.      FG_GETADDR returns the segment address of the active video page.
  6981.  
  6982.      FG_GETPAGE returns the active video page number.
  6983.  
  6984.      FG_GETVPAGE returns the visual video page number.
  6985.  
  6986.      FG_INITEMS initializes expanded memory for use with Fastgraph.
  6987.  
  6988.      FG_INITXMS initializes extended memory for use with Fastgraph.
  6989.  
  6990.      FG_RESIZE changes the dimensions of a video page in EGA and VGA graphics
  6991. modes.
  6992.  
  6993.      FG_SETPAGE establishes the active video page.  It may be a physical or
  6994. virtual page.
  6995.  
  6996.      FG_SETVPAGE establishes the visual video page.  It may be a physical or
  6997. virtual page.
  6998.